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ABSTRACT 

The  cost  of  software  is  fast  becoming  a  major  slice  of  DDD's 
automated  data  processing  buiget.  Most  of  this  oost  is 
directly  related  to  the  maintenance  of  existing  software.  A 
primary  cause  is  poor  or  non-existant  nooumentation  which 
leads  to  high  costs  when  it  cones  time  tD  change  the  soft- 
ware tc  correct  errors,  add  enha ncements,  or  to  comply  with 
changes  in  Federal  regulations/DOD  policies. 

This  thesis  looks  at  the  various  software  engineering 
technigues  available  to  programmers  ani  managers  for  the 
development  of  software  documentation,  k  set  of  guidelines 
for  an  "ideal"  program  maintenance  manual  is  propose!.  These 
guidelines  are  based  on  current  DoD  standards,  examples  of 
software  maintenance  manuals  from  industry,  and  applications 
of  current  software  engineering  prartices. 
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I.  INTRODUCTION 

A.   THE  NEED  FOR  DOCUHENT ATION 

A  recent  Govenment  Accounting  Offlzs  report,  reviewing 
computer  software  maintenance  in  Federal  ADP  agencies, 
produced  some  interesting  observations  *Ref.  1 ]■ 

1.  Two  thirds  of  the  programmers  at  15  Federal  ADP  agen- 
cies spent  their  time  on  software  n  ainter.ancs. 

2.  The  Department  of  Defense  will  spend  approximately  $3 
billion  in  198  1  on  software. 

3.  Agencies  have  made  little  effort  to  effectively 
manage  and  minimize  the  resources  reauired  to  main- 
tain computer  software. 

4.  Software  is  often  maintained  by  Deople  who  did  not 
develop  it. 

5.  Poor  documentation  often  results  in  rebuilding  an 
entire  system  of  programs  because  understanding  and 
modifying  an  existing  program  may  be  more  trouble  and 
expense  then  building  a  new  one. 

The  Federal  Government  is  not  alone  in  its  software  mainte- 
nance 'crises1.  All  ADP  users,  including  private  industry, 
are  being  swallowed  up  by  the  "tar-pits  Df  software  manage- 
ment" as  Fred  Brooks  has  so  vividly  described  [Ref.  2].  The 
costs  to  the  government  and  private  industry,  in  terms  of 
dollars  and  manpower,  is  increasing  at  an  alarming  rate. 
Costs  for  software  (procurenent  and  maintenance)  are 
expected  to  reach  ?200  billion  by  1985.  DOD  estimates  it 
will  spend  330  billicn  by  1990  for  embedded  software  alone 
[Ref.  3,4], 

A  large  share  of  these  costs  are  for  software  mainte- 
nance (see  Figure  1.  1).  Various  studies  have  shown  that 
from  forty  tc  ninety-five  percent  cf  manpower  effort  in  most 
ADP  organizations  is  spent  on  software  maintenance 
[Ref.  5-14]. 
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Figure  1.1    Manpower  Loading  and  Maintenance  costs, 


10 


There  are  many  reasons  for  the  wide  variation  in  effort 
being  devoted  to  software  mainte  nar.oe,  however,  a  definition 
of  maintenance  should  be  presented  first.  Software  Mainte- 
nance is  best  defined  as: 


That  activity  which  is  concerned  with  naking  changes  to 
software  for  the  purpose  of  improving  :r  correcting  the 
software  without  introducing  new  errors  [  Bef •  15]. 

Despite  the  fact  that  large  amounts  of  nanpower  and  other 
resources  are  spent  on  software  maintenance,  few  managers 
comprehend  the  underlying  reasons.  There  are  four  basic 
issues  behind  the  problems  of  software  maintenance: 

•  Maintenance  is  considered  less  glamorous,  interesting 
and  challanging  as  compared  to  system  design  and 
programming;  hence-  there  is  little  incentive  for 
computer  personnel  to  become  involved  in  maintenance 
activities  (or  document  their  time  and  effort  spent,  on 
maintenance) . 

•  During  development  it  is  often  too  early  in  the  project, 
to  forsee  problems  which  may  occur  luring  maintenance; 
as  a  conseguence  maintainability  (the  prcDerty  of  soft- 
ware which  makes  maintenance  activities  easy  to 
perform)  is  not  provided  for  in  the  system  design. 

•  Project  management  dees  not  always  recognize  that  main- 
tainability considerations  should  be  an  integral  Dart 
of  the  design  process. 

•  It  is  very  difficult  to  modify  or  simplify  the  struc- 
ture of  a  program  after  the  program  has  been  written. 
[Ref.  15] 

Weapon   system  software   and   rsal-tiae  system   software 

used  extensively  by  the  Department  of  Defense  (DOD)   suffers 

from  similar  problems  [Ref.  16].    De  Roze  [  Ref .  17]  reports 

that   Air  Force   avionics   software   costs   about    $75   per 

instruction  to   develop,   but   maintenance  costs   are  around 

$4,000  per  instruction.  SAGE,  a  military  iefer.se  system,  had 

an  average  annual  cost  of  20  million  doiiirs  after  ten  years 

of  operation  compared  to  an  original  development  cost  of  250 

million  dollars  [Ref.  18]. 
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The  need  for  efficient,  cost  effecti/e  software  mainte- 
nance  is  important  because  "....of  the  need  to  kesp  DQD 
real-time  weapon  system  software  operating  as  error  free  as 
possible  and  the  need  to  o  heck  the  escalating  cost 
associated  with  modifying  this  software"  \  Ref .  16]. 

Good  documentation  is  seen  is  one  of  the  best  tools  for 
improving  software  maintenance  "  Hef.  19].  In  general,  docu- 
mentation serves  as  a  means  of  communication  within  an 
organization,  especially  over  time.  Documentation  facili- 
tates the  training  of  new  personnel  and  aids  in  modification 
of  a  software  system  by  people  other  than  the  original 
development  programmers.  Silbey  [Ref.  23]  sees  documenta- 
tion as  addressing  three  primary  groups  of  people;  managers, 
programmers/system  analysts,  and  users.  3s  also  argues  that 
the  software  documentation  must  be  clsac,  comprehensive, 
detaiiei  and  well  structured  in  order  to  be  used  effec- 
tively. Good  documentation  can  and  must  provide  a  great  deal 
of  useful  information.  Specifically,  this  information  has  to 
communicate  to  the  maintenance  personnel  enough  ietail  so 
that  enhancements  and  changes  to  the  sof:ware  can  be  easily 
made  and  do  not  produce  unwanted  effects  in  other  parts  of 
the  system  [Ref.  21].  Table  I  lists  examples  of  the  types 
of  information  needed  in  documentation. 

Documentation  has  several  important  uses  beyond  a 
general  description  of  code.  During  the  software  development 
phase  it  is  used  for  communication  between  members  of 
design  team,  for  training  new  personnel  assigned  to 
prelect  and  as  a  basis  for  design  reviews.  During  tae  soft- 
ware maintenance  period  the  documentation  serves  again  as  a 
training  base,  a  guide  for  modification  and  error  checking, 
as  an  organized  collection  of  design  information,  and  as  a 
historical  trace  of  the  software's  production  and  operation. 


ii e  wish  to  emphasize  the  necessity   of  considering 

the  generation   of  timely   dDC umentation  as   an  integral 

portion  of  the  software  deveiDpment  process  [Ref.  22]. 


~    *- 


ne 
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TABLE    I 
Information    Documentation   Provides 

-A   historical    record   of  software   systen    development. 

-A   detailed   analysis    of   software   systen    design. 

-A   well    structured   source    code   listing    with    comments 
on   logic  and    processing   flows. 

-Identification,    logical,    and    physical    characteristics 
of  the    Data   Base. 

-    Requirements,    operating   environment,    and    design 
characteristics    of   the    systsn. 

-Written  instructions  for  non-AD?  personnel  that 
explains  what  the  system  (software  and  hardware) 
does    and  how   to   use  it. 

-Format    of   input  data    and   output    reports. 

-Technical    information   about    data    collsction 
requirements. 

-Detailed   specifications,    descriptions,    and   proceiures 

for   all   tests   and    test    data. 


Do  ci  mentation  is  an  important  product  of  sound  software 
engineering  design  rather  than  a  simple  by-product  of 
design.  Documentation  has  to  be  clear  and  concise.  The  docu- 
mentation format  has  to  be  convenient  and  simple  to  use.  The 
documentation  has  to  be  organized  in  a  hierchical  fashion  in 
the  same  manner  that  the  code  is  structured.  All  design 
decisions  and  their  impact  has  to  be  explained,  and  the 
methodology  fcr  modifications  decided  in  advance.  Version 
control,  and  the  accounting  me-hods  for  n odif icatioa  to  tha 
software,    has    to    be   thorough   [Ref.    23  ]. 
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How  much  and  what  types  of  document  at  Lon  must  be  decided 
during  the  the  design  phase  of  system  development.  Such  to 
often  these  decisions  have  beea  put  cff  until  late  in  the 
system  development  cycle  which  results  in  poor  or 
non-existant  documentation  [Ref.  1]. 

If  we  are  to  improve  the  maintainability  of  large  soft- 
ware systems  we  must  also  "design  foe  change"  as  Parnas 
suggests  [Ref.  24].  This  includes  designing  good  documenta- 
tion to  tell  us  what  a  software  system  does  and  how  it  does 
it. 

B.   PURPOSE  AND  ORGANIZATION  OP  THESIS 

The  purpose  of  this  thesis  is  two-fold.  First  it  will 
examine  and  review  Federal  aid  Department  of  Defense  direc- 
tives on  standards  for  documentation.  Included  will  be  a 
summary  of  the  various  technigies  of  docimentation  from  the 
technical  literature.  Second,  a  design  fcr  a  Programmer's 
Maintenance  Manual  will  be  presented  which  incorporates  the 
latest  concepts  in  software  engineering.  The  reasons  behind 
a  particular  design  and  the  benefits  to  be  gained  will  be 
discussed. 

Chapter  II  of  the  thesis  wiLl  review  the  concept  of  the 
software  life  cycle  and  how  software  maintenance  activi-ies 
relate  to  different  life  cyde  piases.  k  discussion  cf 
current  DOD  directives  in  software  management  that  govern 
weapon  system  software  will  be  given  hare.  lechnigues 
currently  available  for  progranners  and  software  contractors 
for  documentation  will  be  described  in  Ziapter  III.  These 
techniques  include  methods  foe  representing  prcgran  logic 
such  as  structured  programming,  dac=  structures  and 
commented  program  listings. 
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Chapter  IV  contains  a  ^ascription  of  a  Program  mar ' s 
Maintenance  Manual  based  on  DDD  rrquirsnents  for  software 
documentation  and  recommendations  for  changes  to  such  a 
manual.  The  manual  is  designel  from  the  point  of  view  that 
the  program  listing  now  provides  a  great  deal  of  "self- 
documentation"  resulting  fron  idvancss  in  structured 
programming  techniques.  In  addition  the  purposes  aad  goals 
of  a  manual  in  ganeral  are  presented  with  a  view  that  any 
manual  should  be  designed  for  its  intends!  user. 

Finally,  Chapter  7  will  provide  conclusions  and  recom- 
mendations. An  appendix  contains  a  copy  of  the  currant  DoD 
standard  for  a  program  maintenance  nanual. 
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II.  BACKGROUND  OF  SOFTWARE  DOC03ENTATION 

A.   THE  SOFTWARE  LIFE-CTCIE 

All  software,  tactical  weapon  systei  and  general  data 
processing,  must  go  through  several  phases  or  steps  from  the 
time  a  need  for  a  software  system  is  conceived  to  the  point 
where  the  system  is  operational.  This  series  of  steps  is 
generally  referred  to  as  the  software  Life  cycle.  The 
different  phases  of  the  life  cycle  have  various  names  when 
discussed  in  the  literature.  Many  representations  of  the 
life  cycle  are  described.  Figire  2.1  depicts  one  such  model 
based  an  the  well  understool  DOD  system  life  cycle  as 
presented  in  DOD  Instruction  53)0.1.  Figure  2.2  represents  a 
more  general  approach  to  the  life  cycle  phases. 

1"   Software  Development 

In  order  to  understand  better  what  must  be  done  to 
oreate  a  software  system,  an  informal  description  of  each 
phase  is  provided  [Ref.  25]. 

a.   System  Feasibility  and  Analysis  Phase 


The  eventual  user  of  a  systen  discovers  a  need 
for  which  a  computer  based  information  system  or  weapon 
system  seems  to  be  the  answer.  The  nature  of  the  aeei  is 
analyzed;   the   outlines  of   tie  type   3f  system   that  wouli 

satisfy  these  needs  are  established, 
superior  concept  is  defined. 


The  nost  feasible  and 


j     DEFENSE    SYSTEM 
1       LIFE    CYCLE 
1     MAJOR      PHASE 

software 
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5UBPHA3E 
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I           Support 
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Mo  dif ication 

Figure  2.1    DOD  Software  Life  CYcle  Model. 

b.  Requirements    Specification   Phise 

Functional  descriptions  of  the  system  are  devel- 
oped using  a  particular  formal  methodology.  Constraints  on 
the  system's  structure  and  resource  usaje  are  identified. 
Economic  constraints  on  the  development  process  itself  are 
stated.  This  phase  may  be  an  iterative  process  that  oscil- 
lates between  the  statement  of  specifications  and  refinement 
cf  the  iesiqn.  Documentation  standards  ani  management  objec- 
tives should  be  defined  and  listed.  This  ptiase  is  to  oiearly 
and  concisely  state  what  the  system  is  to  do  -  not  ho*  to  lo 
it. 

c.  Product    Design    Phase 

Working  from  the  specifications  the  sverail 
hardware/software  architecture  is  conceived.  The  underlying 
structure  of  the  problem  to  which  this  system  will  be  a 
solution  is  sought  out.  When  this  structure  becomes  clear,  a 
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Figure   2.2        Software   Life   3ycle — Gensral   Schematic. 

assign   of    the    system    is      devissi.      The  dssign    is    r.ecsssariiy 
at    a    gross    abstract    level   of    detail.    The    parts    cf   the    system 

and      their    relationships,         t ha      basic  algori-hms   that      the 

sys-em   will      use,      and  the      majDr   data  cepc esent atior.s    that 

wili    be      needed   are   created.           During  this    phase      the    oasic 

tsst    plan    is   developed,    prefsrrably    by  an    independent    design 
team. 
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d.  Detailed    Design   Phase 

The  major  parts  of  the  design  are  now  refined  In 
detail.  Precise  algorithms  ani  data  strictures  are  defined 
and  spelled  out.  if  not  already  done  in  the  Product  Design 
Phase,  decisions  as  to  which  parts  of  tha  system  will  be  in 
software  and  which  in  hardware  are  made.  Both  detail  design 
and  product  design  may  reguica  several  levels  of  refinement 
and  reiteration. 

e.  Validation  Phase 

At  this  point  in  the  development  a  check  must  be 
made  tc  ensure  the  design,  ia  all  details,  fulfills  the 
specifications. 

f.  Programming,    Cods    and   Da  bug    Phase 

Encoding  of  algorithms  and  data  represeatations 
is  accomplished  in  this  phase.  Individual  modules  are 
prepared  and  tested  individually.  All  basic  debugging  is 
completed  where  possible.  Sone  bugs  may  aot  appear  until  all 
the    system    parts    are    executed   together. 

g.  Integration/System  Testing  Phase 

All  ceded  modules  ire  place!  together  aiocg  with 
a  sample  data  base.  This  produces  a  physical  realization  of 
the  design.  Integration  of  all  the  parts,  systea  testing 
according  to  the  system  test  plan,  ani  performance  evalua- 
tion is  accomplished.  In  many  cases  a  gool  deal  of  radesipr. 
and  reimpiementa tion  may  take  place  ac  this  time  to  force 
the  actual  system  tc  conforn  to  the  specifications  and 
initial  reguirements. 
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2«   Software  Operation 

Everything  that  happens  aftsr  the  software  system  is 
finished,  delivered  and  finally  accepts!  by  the  user  falls 
into  the  operational  half  of  the  life  cyde. 

a.   Maintenance  Phase 

Tauseworthe  offers  a  definition  of  maintenance 
as  "alterations  to  the  software  during  the  post  ielivery 
period  that  do  not  require  a  reinitiation  of  the  software 
development  cycle"  [Ref.  26].  tie  also  views  the  maintenance 
phase  as  any  software  related  activity,  principally  suppor- 
tive in  form,  which  keeps  the  software  system  operational 
within  its  functional  specifications.  Tie  main  activity  of 
maintenance  prcgramers  is  corrective  in  nature,  commonly 
referred  to  as  debugging.  Tauseworthe  considers  enhancements 
as  essentially  changes  to  the  specifications  which  enable 
the  software  to  perform  either  a  new  task,  or  a  different  but 
similar  task.  In  each  case  the  functional  scope  of  the 
program  changes. 

Swanson  [Hef.  27]  d isti nguisaes  between  three 
types  of  software  maintenance;  corrective  maintenance,  adap- 
tive maintenance  and  perfective  maintenance.  Corrective 
maintenance  is  performed  in  response  to  failures  such  as  the 
abnormal  termination  of  a  program  or  tie  failure  to  meet 
performance  criteria.  Adaptive  maintenance  is  performed  in 
response  to  changes  in  environments  such  as  the  installation 
of  a  new  generation  of  system  aardware.  Perfective  mainte- 
nance is  performed  to  make  the  program  a  nore  perfect  iesign 
implementation.  For  example  to  improve  processing  efficiency 
or  to  add  new  features. 

Other  authors  feel  maintenance  has  only  two 
basic  components;  modifications  and  enhancements. 
Modifications   are   any   changes  to   existing   functions   to 
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correct  bugs  and  meet  specifications.  En  hi  p.  cements  are  addi- 
tions of  new  functions  that  wece  in  tha  original  design  but 
never  implemented  or  were  added  as  a  result  of  an  iteration 
of  the  development  cycle  [Raf.  25].  Bodif ication s  and 
enhancements  will  be  the  terms  used  in  tnis  thesis  cd  refer 
to  software  maintenance. 

A  more  accurate  and  definitive  model  of  the 
maintenance  phase  of  the  software  life  cycle  and  of  the  life 
cycle  itself  has  been  propose!  by  the  R3H9  Air  Development 
Center  [Ref.  28].  Figure  2.3  illustrates  two  important 
items  concerning  this  model.  The  first  is  that  the  process 
of  software  development  is  highly  interactive  (indicated  by 
feedback  arrows)  in  order  to  incorporate  new  requirements 
and  changes  to  software  specifications.  Secondly,  and  more 
important,  it  emphasizes  tha  importance  of  the  maintenance 
phase.  The  model  indicates  that  maintenance  phases  are  to  go 
through  the  same  iterative  steps  shown  for  software  develop- 
ment, that  is:  analysis,  specification,  design,  coding, 
validation,  test  and  integration. 

b.   Decommission  Phase 

During  this  phase  an  assesmeit  of  the  software 
is  made  to  determine  its  further  use,  or  to  be  replaced  in 
its  entirety.  This  may  be  due  t3  complete!./  new  reqairements 
where  it  is  considered  more  economical  to  replace  the  soft- 
ware then  to  modify  the  existing  system  d:  where  procurement 
of  new  hardware  dictates  a  new  software  system  be  developed. 

B.   SOFTWARE  MANAGEMENT 

Software  management  is  critical  to  taa  successful  opera- 
tion of  a  large  software  system.  The  decisions  made  by 
managers  of  weapon  system  software  projects  will  lean  the 
difference  between  whether  the  final  product  is  maintainable 
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or  non-i aintainable.  Cave  [Ref.  29]  beLie/es  that:  "Project 
failures  are  generally  the  result  of  improper  or  inexperi- 
enced management  and  not  the  lack  of  technical  ibility." 
Cave  concludes  that  the  successful  development  of  large 
software  systems  can  be  achieved  in  a  consistant  manner. 

In  hooper's  point  of  view  [Ref.  30]  a  common  stumbling 
block  of  software  project  management  has  been  that  manage- 
ment would  always  seek  to  optlaize  the  lavelopment  process 
in  trying  tc  meet  budget  and  sciedule  constraints.  This  type 
of  approach  creates  an  initial  design  with  little  documenta- 
tion resulting  in  increased  difficulty  in  maintaining  the 
software  and  a  corresponding  increase  in  overall  lifa  cycle 
costs. 

While  there  is  no  step  by  step  process  which  will  guar- 
entee  successful  development  of  maintainable  software,  some 
general  policies  may  be  stated  that  are  quite  helpful.  Daly 
[Ref.  31]  lists  several  items  that  have  proved  useful  based 
en  his  experience  in  managing  software  developments.  Table 
II  provides  a  listing  of  two  different  approaches.  Daley 
recommends  Method  1  in  order  to  produce  a  cost-effective, 
more  maintainable  software  product.  Ha  also  recommends  the 
aoplication  of  strict  management  objectives  ta  guide 
developnent. 

1.   DOD  jlanaaement  Policies 

In  December  1974  a  DOD  Software  Steering  committee 
was  established  with  a  goal  of  identifying  critical  weapon 
system  software  problems  and  to  recommend  policies  £oc  their 
solution . 

To  support  this  committee  the  BIIRE  corporation,   in 
conjunction   with    John   Hopkins   University   [Ref.  32,33] 
conducted  a  study  of  weapon   system  softrfire  management. 
was   concluded   that   "...the  najor   contibuting   factor   to 
weapon   system   problems   is   tie   Lack   3f   discipline   and 
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TABLE    II 
Software  Design   Methods 


Method    1 


Method    2 


High   level   language 

Structured   Code 

Composite   design(hierarchy 
of   small   segments) 

Parallel,    top-down,   bottom 
-up  design   all  optimally 
used 

Simple   data   structures   and 
work   areas    (not)    tightly 
packed 


Team 
(egol 

approach   to    design 
ess    programming) 

IBM's    structured 
throuah    for    revie 
detail    design   and 
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wing 
code 

Three 
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a  ms,  one 
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chart 
data 
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s,    sequence 
maps   and   nar 
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Detai 
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led   rest    pla 
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ns  for 

Progr 
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am   maintains 

r    programmer 

d    by    30% 
s 

Only   commercial 
docuientation   generated 
durina    develoDment 


Strict    management 
objectives    established 
to   aiide   development 


Assembly  language 
Tight  3onplex  Cede 
Large  blobs  of  code 

Bottom-up  design 


Tight,  effecient,  data 
structures  and  work  areas 
(every  bit  used,  no  data 
duplicated) 

One  prograa-One  man 
concept 

No  detailed  technical 
review  of  design  or  ccdee 


Original  coder  teste, 
integrates  and  helps 
evaluate  his  program 

Detailed  flow  charts  and 
general  aarratives,  no 
consistency  listing 
with  comnehts 

No  formal  test  plans 

Progran  Maintained  by 

inexperienced  prognihmers 
cr  technicians 

Extensive  n on -commercial 
technical  nsraoranduji 
generated  and  placei  in 
.Library 

Nc  management  objectives 
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engineering   rigor   applied  to   weapon   system   acquisition 
activities," 

The  software  management  steering  committee  incorpo- 
rated this  and  other  ideas  iito  a  comprehensive  plan  to 
include  policy,  practices,  procedures  and  technology  initia- 
tives * Ref.  34].  Parts  of  the  plan  are  intended  as 
supplements  to  principles  stated  in  ODD  Directives  5000.1 
and  5000.2.  The  first  maintenance  management  policy  states 
that  "Ease  of  maintenance  and  a odif icatio n  will  be  a  major 
consideration  of  the  initial  design." 

Two  techniques  are  used  to  provide  management 
control  to  weapon  system  software.  These  are  design  reviews 
and  configuration  management. 

a.   Design  Reviews 

MIL-STD-1 521 (USAF)  annotates  and  describes  the 
reguireients  for  the  following  technical  reviews  and  audits 
on  computer  programs: 

-  Systems   Seguirements    Review     (SRR} 

-  Systems   Design    Review    (SDRl 

-  Preliminary    Design  Review    (?DR) 

-  Critical    Design    Review    (3DR| 

-  Functional  Confirmation   Audit    (FCA) 

-  Physical   Configuration  Audit     (P3A) 

-  Formal    Qualification    Review     (FQR) 

A  software  maintenance  guiisocck  [Ren.  35]  provides  a 
supplement  to  MIL-STD -15 2 1 .  It  describes  items  to  be  taken 
into  consideration  in  order  to  optimize  chs  maintainability 
of  software.  For  specific  definitions  on  any  of  tne  aoove 
items   one    is   referred   to    standard. 
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b.   Configuration  Management 

Configuration  management  consists  of  configura- 
tion identification,  contrsl,  status  accounting  and 
auditing. 

As  part  of  the  proposed  requirements  assigned  to 
contractors  for  the  development  of  weapon  system  software, 
MIL-STD- 1679,  Weapon  System  Software  Development,  stares: 

The  contractor  shall   establish   and    implement   the 

disciplines  of  configuration  aanagement;  namely  configu- 
ration identification,  configuration  control,  and 
configuration  status  accounting.  The  contractor  shall  be 
cognizant  cf  the  requirement  for  long-term  life  cycle 
support  of  the  weapon  system  software.  The  approoriate 
degree  of  configar ation  management  snail  be  applied  to 
ensure  completely  accurate  correlation  between  descrip- 
tive documentation  and  the  progran  in  order  to 
facilitate  post-del iverv  maintenance  by  software  support 
personnel. 

Configuration  ideat if icatioa  iavolves  specifi- 
cally identifying  and  labeling  the  configuration  items  at 
selected  baselines  during  the  software  life  cycle. 
Baselines  are  reference  points  or  plateans  in  the  levelop- 
ment  of  a  system;  a  baseline  is  formally  defined  at  the  end 
of  each  stage  in  the  system  life  cycle.  For  example  the 
functioaal  baseline  is  typically  the  requirements  specifica- 
tions document  that  outlines,  in  terms  both  the  bnyer  and 
developer  can  understand  and  agree  to,  exactly  what  the 
system  will  do.  Configuration  items  are  "is-  individual  enti- 
ties that,  together,  define  and  describe  the  baseline. 
[Ref.  35] 

Configuration  control  proviies  the  means  to 
manage  changes  to  the  (software)  configuration  items  and 
involves  three  basic  ingredients: 


•  Documentation  (such  as  administrative  ferns  and 
supporting  technical  and  administrative  material)  icr 
formally  precipitating  aid  defining  a  proposei  cnar.cra 
to  a  sortware  system. 

•  An  organizational  body  br  formally  evaluating  and 
approving  or  disapproving  a  proposei   mange  to  a  sort- 


.ppro  vir.g 
ware  system. 
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•  Procedures   for  controlling   the   actual   changes  to   a 
sortware  system. 

Software   configuration   status   accounting    provides   the 

mechanism   for  maintaining  a   record   of  hew   the   software 

evolved  and  where  the  software  is   at  an/  current   stage  of 

implementation.   Software  configuration   auditing  provides  a 

means  to  determine  how  well  the  software  product  matches  its 

associated  documentation.   [Ref.  36] 

DOD  Directive   5003.29,   Management   of  Computer 

Resources  in  Kajor  Defense  Systems,  states: 


Defense  system  computer  resources,  including  both 
computer  hardware  and  computer  software  will  be  speci- 
fied and  treated  as  configuration  items. 


The  primary  objecti/e  of  software  configuration 
management  is  the  effective  managemeit  of  a  software 
system's  life  cycle  and  its  evolving  configuration. 
Configuration  is  the  final  fori,  arrangement  or  design  of 
the  software  [Ref.  36].  The  importance  of  configuration 
management  is  that  it  gives  on?  the  ability  to  manage  change 
during  the  development  process.  If  a  program  maintenance 
manual  is  being  designed  in  conjunction  with  and  as  a  part 
of  the  software  system  development,  then  it  should  be  placed 
under  the  discipline  cf  configuration  management.  Changes 
in  the  desiqn  and  contents  of  the  maintenance  manual  can  be 
matched  or  directly  linked  to  ohanges  in  the  software 
system.  This  is  the  intent  of  ODD  Directi/e  5000.29. 

2.   DOD  Directives  and  Standards 

Policies  and  procedures  for  acquisition  of  weapon 
system  software  are  different  in  most  respects  from  t.iose 
used  for  procurring  automatel  data  prDcessing  equipment 
(ADPE) .  The  distinction  made  between  these  two  catagories  of 
automated  systems  is  a  direct  result  of  the  1965  "3rocks 
Act"  (Public  Law  39-306,40,  0.3. C.  759). 
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The  Office  of  Management  an  Budget  (OMB)  and  the 
General  Services  Administration  (GSA)  adninister  tha  Brooks 
Act  guidelines.  ADPE  is  controlled  by  this  Act  a.ii  falls 
under  the  cognizance  of  tie  Assistant  Secretary  of 
Defense(Controller) .  Weapon  system  software,  on  the  other 
hand,  is  excluded  fronm  the  provisions  ot  this  Act  and  fall 
under  the  jurisdiction  of  the  Dffice  of  tie  Under  Secretary 
of  Defense  for  Research  and  Engineering. 

There  is  no  centralized  source  of  guidence  with 
respect  to  weapon  system  software  maintenance  for  DOD 
orgaihza tions  to  follow.  There  are  many  directives,  regula- 
tions, specifications  and  standards  that  impact  on  weapon 
system  software  to  varying  degrees.  The  nost  important  ones 
are  described  here. 

a.   Weapons  Standard  W3  8505 

WS  8506  is  considered  to  be  i  comprehensive  and 
very  good  specification  for  the  documention  of  program 
development,  particularly  in  view  of  its  early  publication 
date  (1971).  One  of  its  strong  points  is: 


A  strategy  for  making  each  level  :>  f  documentation 
responsive  to  the  next  UDoec  level  (subproaram  iesign 
under  program  design^  which  represents  foresight  in  the 
use  of  toD-down  iesign  prior  to  the  tine  this  term  was 
in  vogue  [ Ref .  15]. 


It  dees  not  include  such  programming  techniques  as  struc- 
tured programming,  but  this  technique  wis  not  developed  at 
the  time  of  its  publication. 

Its  weaknesses  include  a  lack  of  change  proce- 
dures, documentation  standards  for  diagrams  (such  as 
Hierarchy  Input/Output  or  HI?D)  and  regression  testing 
[Ref.  15]. 


29 


b.       MIL-STD-483     (USAF) 

MIL-STD-483  (USAF)  ,f  Configuration  Managenent  for 
Systems,  Equipment,  Munitions,  and  3omp.it  erPrograras, "  1  Jane 
1971,  defines  the  entire  spectrum  of  artivites  associated 
with  controlling  changes  (a  critical  naei  for  maintenance 
work)    to    computer  programs. 

C.       MIL-S-52779     (AD) 

MIL-S-52779  (AD),  "Software  Quality  Assurance 
Program  Requirements,"  5  April  1974,  rsjiLrss  that  a  Quality 
Assurance  Program  (QAP)  be  implemented  specifically  for  the 
dsvelopaent  of  computer  prograns  and  related  documentation. 
Even  though  this  standard  is  concerned  with  the  development 
phase,  it  is  important  because  it  can  iirectly  affect  the 
quality  of  software  documentation. 

d.   SECNAVINST  3560.  1 

SICNAVINST  3560.1,  "Department  of  the  Navy 
Tactical  Digital  Systems  Documentation  Standards,"  3  August 
1974,  identifies,  names  and  describes  that  set  cf  documents 
necessary  to  supprt  both  the  development  and  maintenance  of 
tactical  software.  A  review  of  3560.1  was  conducted  to 
determine  how  well  this  standard  supports  software  mainte- 
nance activity  [ Ref.  37].  As  noted  by  this  review  there  are 
some  positive  and  negative  aspects  to  tie  standard.  Some 
positive  aspects  include: 

-  Applicable  document    statements. 

-  Resource    budgets     (time, space  )  . 

-  Numerous   examples. 

-  Content    check   lists. 

-  Interface    descriptions. 

-  Test    coverage. 

-  Detailed  Table  of  Contents  for  each  sd ecif icat ion. 
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The  deficiencies  of  the  standard  include  a  lack 
of  requirements  for  the  subject  of  tracaaDility ,  a  need  for 
increased  emphasis  on  vaiidatiDi,  and  tie  use  of  inconsis- 
tant  or  non-defined  terminology.  The  review  indicates  the 
standard  seems  more  orientated  towards  software  development 
then  to  softwre  maintenance.  Ths  review  aLso  notes  the  stan- 
dard^ strong  orientation  towards  the  tfa/y's  tactical  data 
system.  Scneidewind,      [Ref.    37],         racommends    "...a      more 

general   orientation    might      be   preferable    to    achieve      a    wider 
applicability  to    a   variety   of   software   systems." 

e.       DCD    DIRECTIVE    5300.29 

DOD  DIRECTIVE  5000.29,  "Management  of  Computer 
Resources  in  Major  Defense  Systems,"  26  ipril  1976,  estab- 
lishes DOD  policy  for  the  management  and  control  of  computer 
resources  during  system  acquisition.  Maintainability  of 
software  is  called  out  as  a  major  consiieration  during  the 
initial  design.  It  also  directs  that  support  items  required 
for  cost  effective  maintenance  be  specified  as  deliverable 
items.         Documentation      is   listed   and      denized    as      a    suoDorc 


item. 


f.       MIL-STD-1521      (USAF) 


MIL-STD-1521  (USAF),  "Technical  Reviews  and 
Audits  for  System,  Equipment  and  Computer  Programs,"  1  June 
1976,  prescribes  the  requiremsa ts  for  tie  conduct  3f  tech- 
nical reviews  and  audits  in  conjunction  with  the  documents 
defined  in  MIL-STD-483.  Direction  is  provided  concerning  the 
review  and  audit  of  computer  program  configuration  items  and 
their  associated  documentation.  Each  type  of  review  du  audit 
is  described  in  an  appendix  to  the  standard  and  can  serve  as 
a  basis  for  checking  compliance  with  maintainability 
requireaents.  The  documentation  discussed  here  is  related 
more  toward  system  design  reviews  then  towards  the 
documentation    of    program    listings. 
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g.       DODINST    5000.31 

DOD  Instruction  5330.31,  "Iiterim  List  of  DOD 
Approved  High  Order  Programming  Languages  (H0L»  ,  ■  24 
November  1976,  specifies  which  HOL's  are  approved  for  use  in 
conjunction      with      DOD  Directive      5300.29.  Although      this 

instruction  allows  for  certain  exceptions,  it  attempts  to 
reduce  the  proliferation  of  BDL's  in  defense  systems  by 
limiting  new  development  to  six  approved  languages:  C'AS-2, 
SPL-1,  TACPOL,  JOVIAL,  COBOL,  and  F3RTRAN.  Its  major  impact 
is  in  the  standardization  of  compilers  and  in  preventing 
each  DoD  activity  from  developing  its  own  unigue  programming 
language . 

h.       MIL-STD-1679     (NA7Y) 

MIL-STD-1679  (NAVI)  ,  "Weapoi  System  Software 
Development,"  1  December  1973,  establishes  uniform  require- 
ments for  the  development  of  weapon  system  software  within 
DOD.  Strict  adherence  to  the  provisions  of  this  standard 
will  help  ensure  that  the  tactical  software  so  developed 
will  be  improved  over  current  versions  d£  tactical  software. 
MIL-STD-1679  includes  developments  in  programming  tech- 
nology, and  management  such  as  structure!  programing  and 
design  walkthroughs,  which  have  occured  since  the  release  of 
WS  8506.  It  stipulates  the  use  of  higti  order  languages  and 
specifies  the  use  of  configuration  management  for  corre- 
lating documentation  with  the  progran  for  maintenance 
purposes.      [ Ref .    15] 
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III.  TECHNIQUES  TO  SUPPQRr  SOFTWARE  DOCUMENTATION 

A.   STROCTURED  PROGRAMMING 

There  are  several  definitions  and  gsals  of  structured 
programming.  Some  of  these  goals  relats  to  the  design  and 
tasting  of  large  software  systems.  Ons  particualr  goal  of 
structured  programming  is  to  organize  and  discipline  the 
program  design  and  coding  process  in  order  to  reduce  logic 
type  errors  [Ref.  38].  It  is  generally  accepted  that  the 
goals  of  structured  programming  include  those  of  software 
engineering.  In  particular  these  goals  are:  modif lability , 
efficiency,  reliability,  and  understandibility  of  the 
program  code  [Ref.  39]. 

What  must  be  shown  is  how  struotured  programming 
supports  documentation.  This  is  not  easy  to  do  because 
structured  programming  is  not  a  universal  and  well  defined 
concept.  it  is  defined  in  many  places,  "Ref.  39,40,42],  but 
B3t  always  consist  ant ly.  However,  its  essence  is  fairly  well 
understood.  It  is  the  practice  of  of  programming  using  a 
limited  but  sufficient  set  of  control  constructs  Figures  3.1 
and  3.2  illustrate  the  five  basir  control  constructs  as 
reguired  by  MIL-SID- 1 679. 

Myers  [Ref.  18]  provides  a  List  of  s=ven  basic  elements 
of  a  structured  program  which  shouid  be  apolied  to  help 
reduce  program  complexity  and  promote  clarity  of  thought  by 
the  programmer. 

•  The  code  is  constructed  from  sequences  of  basic 
elements. 

•  Use  of  the  GOTO  statement  is  avoided  whenever  possible. 

•  The  code  is  written  in  an  acceptable  style  (e.g.  use 
meaningful  variable  names,  avoid  statement  ^ables, 
avoid  .Language  tricks). 

•  The  code  is  properlv  indented  on  the  listing  so  that 
breaks   in  execution'  sequence  can   oe  easily   :ollowei 
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Sequence 


Process  5' 
I   Process ~B' 


SEQUENCE 


If-Tian-Else 


^Erse"" 
Process 


TfTsn"- 
Process 


IF    THEN    ELSE 


Do-Whils 


I       ^vEiIe""! 
?ro:9ss      | 

i ; 


DO    WHILE 


Figure  3.  1        Basic    Control   Constructs. 
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(e.g.   a   DO  statement  :aa   be  easily  matched   with  the 
ENDDO  statement  ending  th;  loop) . 

•  There  is  only  one  point  of  entry  ani  one  point  of  exit 
in  tne  code  for  each  module. 

•  The  code  is  physically  segmented  on  the  listing  to 
enhance  readibilty.  rhe  executable  statements  tor  a 
module  should  fit  on  a  single  page  of  the  listing. 

•  The  code  represents  a  siaple  and  straightforward  solu- 
tion to  the  problem. 

Figure  3.3   provides  an  example   of  structured   and  jnstruc- 

tured  coding.     A  structured  program  is  structure!   in  two 

different  ways.   First,  it  is  structured  with  regard  to  flow 

of  control   and  execution   of  the   progran.   Second,    it  is 

physically  structured  by  the  use  of  indentation. 

Another  way  of  viewing  structured  programming  is  to  see 
it  as  those  attributes  of  a  program  that  contribute  to  the 
readibilty  of  its  form.  For  example  coisider  the  ievelop- 
ment  of  a  file  management  system.  Ob/iously  one  required 
function  of  such  a  system  would  be  the  capability  to  search 
for  a  given  file  identified  by  a  specific  name..  Figure  3.4 
illustrates  such  a  function  as  coded  in  the  recently  devel- 
oped DOD  high  order  language  aDA  (see  "Ref.  44  ]  for  details 
on  the  ADA  language)  .  As  can  be  seen  in  Figure  3.4  struc- 
tured programming  makes  for  a  aore  readable  and  discernible 
sequence  cf  code.  The  main  tenants  of  structured  programming 
are  displayed,  that  is;  hierarciic  relationships  between  the 
lines  of  code,  a  consistant  indentation  policy,  and 
begin-end  groupings  which  aalce  it  easier  to  follow  the 
program  flow.  Comments  are  ased  extensiviy  tc  introduce 
each  new  module  and  structure. 

The  results  of  structured  programming  are  readily  appa- 
rent with  easy  to  read  code  ani  easy  to  follow  logic  flow. 
Functions  and  procedures  are  confined  to  iiscrete  areas  in 
the  program  listing.  The  objective  is  to  nake  the  code,  in  a 
very  meaningful  and  useful  way,  self-documenting,  thus 
reducing   the  need   f cr   external   documents  describing   the 
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Do-UntiL 


Process 


|~7rocess   a 


DO    UNTIL 


Case 


CASE 


Figure   3.2        Basic    Control    Constructs. 
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UNSTRUCTURED 


IF 
IF 
L  f 
GOT 

label  m  M  f 
GOT 

label  q  IF 
A  f 
B  f 
C  f 

label  r  IF 
D  f 
GOT 
IF 


label 
label 
label 
label 
label 

label 

label 

label 
label 


v  IF 

J  f 
k  K  f 

END 

f  F  f 
GOT 

t  IF 
A  f 
B  f 
GOT 

a  A  f 
B  f 
G  f 

u  IF 
H  f 
GOT 

w  IF 
I  f 

V  IF 
J  f 
GOT 


p  GOTO 
w  GOTO 
unction 
0  label 
unction 
0  label 
q  GOTO 
unction 
unction 
unction 
NOT  r  G 
unction 
0  label 
s  GOTO 
unction 
NOT  v  G 
unction 
unction 
functi 
unction 
0  label 
t  GOTO 
unction 
unction 
0  label 
unction 
unction 
unction 
NOT  U  G 
unction 
0  label 
NOT  -  G 
unction 
NOT  7  G 
unction 
0  label 


label  q 
label  m 


label  t 
OTO  label  s 

E 

label   f 
oto   label  < 

on 

v 

label  a 


OTO    label   w 

u 

OTO    label   y 

OTO    label   k 
k 


« 


STRUCT 'J  RED 

IF  ?  T3EN 

A  Ei net ion 

B  function 

2 

IF  3  THEN 

3   IF  t  THEN 

G  function 

U  DOWHILE  u 

H  function 

4  SNDDO 

I  function 

3   (ELSE) 
3   SNDIF 

2 

ELSE 

C  function 

3   DDWHILE  r 

D  function 

3   ENDDO 

3   IF  s  THEN 

F  function 

3   ELSE 

E  function 

3  ENDIF 

2 

ENOIF 

2 

IF  7  THEN 

J  function 

2 

(ELSE) 

SNDIF 

2 

1  ELSE 

2 

IF  V  THEN 

1  function 

2 

ELSE 

L  function 

2 

SNDIF 

1  El 

&DIF 

K 

fu not  ion 

E 

VD   fjnetion 

Fiqure  3.3        Structured   vs.    Unstructured   Coding. 

code.  This  has  an  effect  oi  the  design  of  the  document 
called  the  Prcqram  Maintenance  Manual  and  will  be  discussed 
in    detail    in   Chapter    IV. 
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function   SEARCH    (FILE    NAME;KSY    TIPE) return 

FILE    INDEX    is  "  " 

begin 

—  Look. for   the  specified    Key   recori    ia   the 

—  specified    file,    returning   the    iniex    of    its 

—  position 

for    I    in    FILE    INDEX ' FE RST. . FILE    INDEX* LASI    loop 

—  Search   the    whole    lata   base,    from    first    to 

—  last 

if    FILE    MAP(I)     /=    N3LL 

—  Checlc   data    base   for   i    nail    or    a 

—  match 


and  then  FILE  MAP(I)  =  FILE  NAME 
and  then  FIL3"*KEY(I)  =  KEY  TYPE  then 
return  (I)  ; 


end  if; 
end  loop; 
raise  BAD  FILE; 

—  Raise  an  exception  if  the  desired  record 

—  is  not  found 
end  SEARCH; 


Figure  3.4    File  Search  Function. 

B.   MODULARIZATION 

Modules  are  the  building  blcoks  of  software.  3coi 
modular  programming  usually  requires  that  external  inter- 
faces, such  as  input/output,  be  isolated  into  seperate 
modules.  Modular  programming  itself  is  "he  practice  of 
implementing  software  in  snail,  functionally  orientated 
pieces.  These  pieces  are  usuall/  implemented  as  subroutines, 
functions  or  clusters  of  functions.  Each  module  is  devoted 
to  cne  or  mere  tasks  related  to  a  function;  the  moiule  may 
be  accessed  from  one  or  several  plaoes  in  the  software 
system. 

Modularity  is  of t  as  defined  in  terms  of  properties  poss- 
essed by  "modular"  systems. 

A  program  is  modular  if  it  is  written  in  nany  relatively 
independent   parts  or   modules  which   haze  well   defined 
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interfaces  such  that  each  module  makes  no  assumptions 
about  the  operation  of  other  modules  except  whit  is 
contained  in  the  interface  soe cificatiois. 

Modularization  consists  of  dividing  a  program  into 
subprograms  (modules)  which  can  be  compiled  separately, 
but  which  have  connections  with  other  i»odules...A  defi- 
nition of  "good"  modularity  must  emphasize  the 
requirement  that  modules  be  as  disjoint  as  possible. 

Modular  .programming  is  the  organizing  of  a  conplete 
program  into  a  number  of  small  units. .. where  there  is  a 
set  of  rules  which  controls  the  characteristics  of  these 
events. 

Modularity  deals  with  how  the  structure  of  an  object  can 
make  the  attainment  of  some  purpose  easier.  Modularity 
is  purposeful  structuring  [Ret.  39]. 

There  is  a  trend  towards  defining  modules  in  terms  of  the 
number  of  lines  of  code  they  contain.  Programming  standards 
frequently  contain  a  somewhat  negative  approach  such  as 
"...modules  shall  contain  less  than  X  liies  of  code."  Some 
authors  feel  that  the  size  aspect  is  not  as  important  to  a 
module  as  its  functional  aspect.  In  other  words  a  small 
complex  module  may  be  more  difficult  to  understand  than  a 
large  well  structured  module.  However,  the  majority  still 
favor  limiting  module  size,  when  possible,  to  less  than  100 
lines  of  code  in  order  to  maintain  modiles  as  "discrete" 
entities  and  to  aid  comprehension  [Ref.  39,40]. 

There  are  many  advantages  to  using  modules.  Parnas 
[Ref.  24]  argues  that  the  most  important  aspect  of  moduiari- 
zation  is  the  ability  to  anticipate  and  design  for  changes. 
If  the  function  of  a  module  changes,  thit  module  alone  has 
to  change.  If  the  need  for  a  function  arises  during  the 
design  phase,  a  module  with  tais  function  can  be  invoked  at 
the  point  of  need.  If  an  error  in  the  program  is  found,  the 
probability  is  that  its  correction  will  be  limited  to  one 
module.  Once  a  module  has  been  tested,  and  can  be  compiled 
seperateiy,  it  can  be  reliably  used  ia  different  piaces  in 
the  program.   [Ref.  4  1] 
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Since  modularization  makes  the  structure  of  a  program 
easier  to  understand  while  looaliziig  functions  and 
processes,  the  need  for  external  docuisntation  is  again 
reduced. 

As  a  final  note,  there  has  to  be  a  distinction  made 
between  modualrity  and  structured  programing. 


._y  language  (_ 
opposed  to  assembler  enhanced  with  strong  macro  capa- 
bility) .  In  contrast,  nodularity  is  usable  in  all 
domains.  Thus,  the  line  between  modularity  and  structure 
may  be  a  tenuous  one  to  wait,  but  it  is  an  important 
one.  Note  that  good  modules  aay  or  may  not  possess  good 
program  structure  and  that  bad  modules  nay  also  possess 
good  program  structure.  The  two  subjects  are  discernable 
[Ref.  43]. 


C.   DATA  STRUCTURE 

In  eome  programming  languages  there  are  at  least  two 
ways  of  working  with  a  string  of.  bits  or  characters.  Dne  way 
is  to  declare  the  string  as  part  of  a  stricture  (Figure  3.5) 
and  thea  manipulate  the  string  ay  name: 

OTHER  STRIN3  =  CHARACTER  STRING 


Structure  DATA  STRUCTURE;  begin 

item  CHARACTER  SIEOG  5  characters; 
item  OTHER  VARIABLE  32  bits; 

end  Structure; 


« 


Figure  3.5    Example  of  a  Data  Structure. 
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A  second  method  is  to  use  a  byte  manipul at ing  function  to 
define  the  desired  string  at  2  very  point  of  usage  in  the 
program: 

OTHER_STRING  =  BYTE  (CH  ARACTER.ST  RI  NG,  5)  ; 

Suppose  the  character  string  named  0THER_5rRING  is  utilized 
100  times  in  the  program.  In  order  ta  change  the  string 
fnrmat  ising  the  first  method  (Figure  3.5i,  only  one  easily 
identified  line  of  code  has  to  change.  In  the  seccr.d  case 
there  are  100  lines  to  change  throughout  the  progran. 

Languages  may  or  may  not  support  such  data  structuring. 
COBOL  and  PL/I  provide  elaborate  data  strictures  for  format- 
ting report  data  for  printout.  In  addition  such  changes  as 
stripping  off  leading  zeros,  inserting  a  decimal  point, 
adding  check  protect  characters,  and  inserting  a  leading 
dollar  sign  are  easily  accomplished.  \t  the  other  extreme 
FORTRAN  and  BASIC  offer  no  data  structure  capability  beyond 
the  array  [Ref.  43]. 

Data  structure  impacts  the  areas  of  software  design  and 
software  maintenance.  One  metlodology,  called  the  Jackson 
method  * Ref.  45],  stresses  designing  the  program  structure 
by  first  locking  at  the  data  structures.  According  to 
Jackson,  an  algorithmic  structure  is  highly  related  to  data 
structure;  programs  that  obey  data  structure  design  will 
have  a  more  maintainable  program  structure  as  well. 
Obviously  different  application  areas  ha/e  different  levels 
of  need  for  data  structure  orientation. 

One  of  the  noticable  effects  of  large  software  systems 
is  that  algorithms  end  up  transforming  3ne  data  structure 
into  another  data  structure.  This  results  in  what  Jackson 
terms  a  "structure  clash."  The  reason  foe  this  cccnrir.g  is 
commonly  a  proliferation  cf  unnecessary  cnde,  lack  of  struc- 
tured programming  goals,  or  lack  of  design.  Sometimes  the 
"clash"   is    a   result   of   maintenance,     corrective   and 
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enhancement,  where  the  changes  have  added  information  or 
changed  the  data  structure  to  meet  tha  current  need.  Two 
solutions  have  been  proposed  in  this  area.  Grouping  or 
"clustering"  of  data  and  abstract  data  typing  [  Ref .  43,  i*9]. 

Where  a  set  of  data  declarations  interrelate,  either  by 
function  or  by  context,  they  should  be  grouped  together  for 
ease  of  understanding  and  modification  into  one  block.  This 
is  the  "clustering"  concept.  If  a  change  is  needed  it  can  be 
isolated  into  one  block.  Only  those  modiles  which  use  that 
block  of  data  need  be  recompiled. 

With  the  concept  of  abstract  data  typing,  such  as  used 
by  PASCM.  and  ADA,  [Ref.  4H  ]  all  data  mist  be  explicitly 
declared  to  be  of  a  particular  type.  Certain  types  are 
defined  in  the  language,  but  these  must  be  supplemented  by 
programs er-defined  types.  Associated  with  a  type  is  a  set  of 


type  RECORD  F0RMAT_1  is 
record" 


EMPLOYEE  NAME:  array(1..30|  3f  CHARACTER; 

EMPLOYEE-RATE:  float; 
EMPLOYEE-HOURS:  integer  range  0..99; 
EILE1  RECORD:  RECORD  FORMAT  1 


Figure  3.6    Example  of  an  kDk   Data  Structure. 

legitimate  values  which  objects  of  a  type  nay  assume  and  a 
set  of  operations  which  may  De  performed  on  that  type. 
Figures  3.5  and  3.6  show  examples  of  ADA    lata  structures. 

This  kind  of  typing  has  three  characteristics:  (1)  -he 
properties  of  a  type  are  defined  centrally  at  the  ""ype 
declaration,  and  if  they  change  they  neei  only  be  changed  in 
cne  place;   (2)   only  the  abstract  properties  of  a  t/pe  need 
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be  known  to  reference  data  of  that  type,  iith  implementation 
aetails  "hidden"  in  the  declaration;  and  (3)  strong  type 
matching  may  be  enforced  by  the  compilsr,  eliminating  type 
mismatch  errors  as  a  reiiabilit y/maia tainability  issue 
[Ref.  43,44]. 

As  a  final  consideration,  it  is  always  important  to  name 
data  effectively.  Meaningful  names  are  always  preferable. 
EMPLOYEE_NAME  conveys  far  mors  information  about  the  data 
value  then  EMFNAM.  This  supports  the  goal  of  readability  and 
the  ultimate  goal  of  having  tie  program  be  as  self 
documenting  as  possible. 

D.   DATA  COMMUNICATION 

There  are  two  basic  types  of  data  comn an ication,  intra- 
program  and  inter-program.  Ir.tr a-pcogram  data  communication 
is  essentially  communication  between  modiiss.  This  can  be 
accomplished  by  paramenter  lists,  global  (or  common!  data 
and  a  recent  concept  called  a  data  "cluster".  A  cluster  is 
where  a  constrained  " semiglobal"  data  bass  is  shared  among  a 
limited  number  of  processes  or  functions.   "Ref.  42,43,44] 

A  parame-er  list  identifies  only  chose  data  items  and 
formal  parameters  used  by  each  individual  moduls.  The 
preferred  method  of  intra-pcog cam  coamua  ication  is  by  the 
use  of  a  parameter  list  [Ref.  43].  The  main  advantage 
gained  is  chat  all  data  used  by  the  modal =  are  identified 
and  isolated.  It  is  not  possible  foe  ths  nodule  to  have  a 
surprise  effect  on  the  code  which  invokes  the  module. 

Glooal  variables  are  used  for  largs  quantities  of  data 
when  it  is  not  convenient  to  specify  sucn  a  large  parameter 
list  at  each  point  of  call.  lost  authors  recommend  minim- 
izing tie  use  of  global  data  for  good  modilar  and  structured 
programs.  The  reason  for  limited  use  is  that  a  module  may 
modify  a  global   value  whose  original  valis   was  critical  to 
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the  calling  environment.    This  may  lead  t3   undesirable  and 
untracable  side  effects.   [Raf.  40,42] 

A  side  effect  is  one  brought  about  other  than  via  a 
parameter  mechanism.  It  is  generally  considered  rather 
undesirable  to  write  subprograms,  especially  functions, 
which  have  side  effects.  Howsver.  soma  side  effects  are 
beneficial.  Any  subprogram  which  performs  input-cutout 
has  a  side  effect  on  the  file;  a  function  delivering 
successive  numbers  of  a  sequence  of  random  numbers  only 
works  because  of  its  side  effects;  if  one  needs  to  count: 
how  many  times  a  function  is  called  then  we  use  a  side 
effect;  and  so  on.  Care  must  be  taken  when  using  func- 
tions with  side  effects  that  t he  function  does  not  cause 
errors  in  other  sections  of  tie  program.   [Ref.  44] 


The  cluster  concept  is  an  attempt  to  fulfill  the  need 
for  global  variables.  A  data  oase  and  its  family  of  manipu- 
lating procedures  is  isolated  from  the  rest  of  the  program. 
A  program  needing  some  or  all  of  of  the  clustered  data  must 
explicitly  import  it.  The  cluster  itseLf  can  distinguish 
between  data  and  procedures  which  may  b»  exported  or  not. 
The  sida  effect  problem  is  at  least  isolated  and  bounded. 
[Ref.  40,42] 

Inter- program  data  communication  is  provided  either  by 
passing  data  flags  and  blocks  through  an  operating  system 
communication  area,  or  by  passing  larger  volumes  of  informa- 
tion on  files.  The  UNIX  concept  of  "pipes"  in  which 
predefined  files  are  automatically  passed  from  one  program 
to  the  next  is  an  exampia  of  this  type  of  data 
communication.   [Ref.  47] 

The  proper  use  of  data  conn unication  clarifies  program 
flow  and  tracability  of  processes.  This,  of  course,  supports 
the  maintenance  programmer's  task  in  the  correction  of 
program  errors  and  in  his  understanding  of  the  program's 
documentation. 
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E.   HIGH  ORDER  LANGUAGES  (HOL»S> 

High  order  languages  are  those  computer  languages  which 
are  essentially  machine  (hardware)  independent.  This  is  in 
contrast  to  assembly  languages  that  were  designed  for  a 
particular  hardware  architecture.  For  example,  the  INTEL 
8D80  assembly  instruction  set  will  not  work  at  all  on  a 
Motorola  6800  based  machine.  Iq  contrast  a  standard  FORTRAN 
program  can  easily  be  used  on  any  computer  with  an  appro- 
piate  FORTRAN  compiler. 

High  order  languages  tend  to  support  the  concepts  just 
discussed  (structured  programming,  modularity,  data  struc- 
ture, etc.)  to  varying  degrees.  FDRTRAN  offers  modularity, 
but  is  limited  for  program  structuring  and  has  almost  no 
capabilty  for  data  .structuring.  COBOL  has  excellent,  robust 
capabilities  for  data  structures.  Other  languages  have  their 
strong  and  weak  points.  [Ref.  43]  Examples  of  good  H3L  code 
may  be  found  in  several  references  "Ref.  19,42]. 

Documentation  is  supports!  by  High  Order  languages 
(HOL's)  if  the  language  is  readable.  FORTRAN  is  United  in 
this  respect  because  of  its  six  character  limit  on  lata  and 
variable  names.  Some  HOL's,  APL  for  example,  provide  no 
rsadabilty  at  all.  APL  is  very  difficult  to  understand  after 
it  is  written  down,  even  by  the  person  who  designed  the 
program. 

ADA,  the  new  programming  language  developed  by  the 
Department  of  Defense,  promises  to  offer  the  best  supper*. 
for  just  about  all  the  major  software  engineering  princi- 
ples. iDA  is  a  large  language  since  it  addresses  so  man/ 
different  issues.  Some  of  the  key  goals  of  ADk  are  listed  in 
Table  III  [Ref.  «*4  ]. 

The  overall  objective  of  the  Department  of  Defense  is  to 
provide  one  standardized  language  for  use  in  all  tactical 
embedde!   systems.   This   can   provide  substantial   economic 
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TABLE    EII 
Key   Goals    of   ADA 

READABILITY 

It    is 

mere  o 
theref 
A  PL. 

STRONG    TYPING 

This   insures   that    each    object    has    a    clearly    defined 
set    of    values   and    prevents    confusion    between    logically 
distinct    conceDts.    As    a   consequence    many    errors    »c= 
detected   by  the   compiler   which   in    other    languages 
would    have    led  to    an    executable   but    incorrect   program. 

PROGR AM MING-IN-THE -LARGE 

Mechanisms   for  encapsulation,    seperate    compilation, 
and  library   management    are   necessary   for    the   writing 
of   portable    and  ma  intainaole    programs    Df    any   size. 

EXCEPTION    HANDLING 


It  is    a    fact   of   life    that    prograas   of    consequence 
are   rarely   correct.   It   is   necessary  to    provide  a 
means    whereby   a   program  can  be   constructed    in    a 
layered   and    partitioned   way   so   that    odi sequences 
of  errors    in   one   part    can   be    contained. 

DATA    ABSTRACTION 

be    obtained 


»pt    sep  . 
operations   on   the    data. 

TASKING 

For  many  applications  it  is  Important  -hat  the 
program  be  conceived  as  a  secies  of  Dacailel 
activities  rather  than  just  is  a  single  sequence 
of  actions.  Building  agprcpiate  facilities  into  a 
language  ether  than  adding  -hem  on  via  oaiis  to  an 
operating  system  gives  better  portability  and 
reliability. 

5INERIC  0]i ITS 

In  many  cases  the  logic  of  part  of  a  program  is 
independent  of  the  tyoes  of  values  being  manipulated 
A  mechanism  is  thererore  necessary  for  the  creation 
of  related  pieces  cf  Drogram  from  a  single  template. 
This  is  particularly  useful  for  the  crsation  or 
libraries. 
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benefits  by  reducing  the  number  of  diffarant  types  of  compi- 
lers needed.  It  also  promotes  familiarity  by  programmers  and 
maintenance  programmers.  Improved  progran  clarity  aid  read- 
ability should  also  simplify  the  document ation.   [Ref.  46] 

F.   THE  PROGRAM  LISHHG 

If  the  overall  goal  is  to  reduce  the  quantity  and  cost 
of  documentation  and  improve  its  quality  and  usefulness  to 
the  maintenance  programmer,  then  it  is  highly  desirable  that 
programs  be  made  as  self -doouae nt ing  as  possible.  In  this 
manner  one  can  substantially  reduce  the  necessity  to  main- 
tain multiple  forms  of  documentation  representing  the  same 
logic.  Many  authors  advocate  such  an  approach  through 
structured,  well  commented  program  listings.  Myers  [Ref.  13] 
states: 


Since  we  already  have  the  0012,  rfhy  not  let  it  serve  as 
the  logic  documentation?...  additional  documentation 
such  as  a  flowchart  would  be  undesirable  because  it 
would  be  redundent  with  the  code.  Redundancy  in  any  type 
cf  documentation  should  be  avoided  because  it  increases 
the  chances  of  conflicts.  Furthermore,  unless  care  is 
taken  to  update  the  documentation  (whirh  is  more  diffi- 
cult if  the  logic  documentation  is  physically  seoerated 
from  the  cede),  redundent  documentation  often  becomes 
totally  useless  after  the  cola  is  modified  a  few  times. 


Siass  [Ref.  43]  also  agrees  with  this  point  of  view  stating: 


The  documents,  when  they  do  exist,  are  generally  written 
to  conform  to  a  seperate  set  of  requirements  which 
specify  what  the  software  documentation  is  to  contain, 
fcll  too  frequently,  these  requ ir ensi t s  provide  for 
irrelevent  cr  useless  information  that  the  maintainor 
really  needs.  So,  in  a  real  sense,  the  document,  which 
is  supDcsed  to  be  a  clarifyina  piece  of  materia^.,  ends 
up  obscuring  the  needed  irf or  nation. 


Because  documentation  is  seperate  from  the  software 
product  itself,  it  is  also  frequently  out  of  date. 
Ideally,  the  document  would  ae  a  perfect  reflection  of 
the  program.  In  actual  fact,  this  is  rarely,  if  ever, 
true.  The  document ation  can  therfore  be  misleading.  Who 
in  their  riaht  mind  would  attempt  to  mate  corrections  to 
a  program  after  reading  only  the  program  documentation 
and  not  the  listing? 
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program    car.    be   met    and    in  fast    exceeds!    by    reguiring    the 
same  information   in   the   listing. 


DOD,  in  general,  supports  this  point  of  view  and  gives 
explicit  direction  for  what  constitutes  a  well  conmented 
program  listing  in  MIL-STD-157 9.  However,  MIL-STD- 1679 , 
SECNAVIMST  3560.1  and  other  directives  require  extensive, 
detailed,  external  documentation  (i.e.,  other  than  the 
program  listing)  to  be  produced.  Dne  valid  reason  for  this 
requirement  is  the  need  for  extensive  design  reviews 
required  by  configuration  management  teciniques.  k  second 
reason  is  that,  until  the  nid-1970's  and  the  advent  of 
sofware  engineering  techniques  as  discussid  in  this  chapter, 
the  program  listing  did  net  convey  a  great  deal  of  informa- 
tion, h  large  amount  of  English  text  was  needed  to  explain 
the  design  and  structure  of  the  software  and  its  associated 
data  bases.  Even  Glass  admits  that  some  external  documenta- 
tion will  always  be  required  to  give  an  overview  of  the 
structure    and    the    software's   design   history    [Ref.    <*3]. 

This      "external"      documentation      is      aimed      at      specific 
users.    Operator's    Manuals    are    is  ant    to    be    read   by   operators. 
SDecificat ions   are      meant    to   be      read    by    ooth      customers    (to 
give   them      the   ability  to      determine    that    the      problem    being 
solved   is    the      one   they    want   solvedi  an3    designers.         lest 

documents  are  meant  to  be  real  by  custoners,  to  determine 
that  proper  reliability  techniques  are  employed,  and 
testers.  The  main  problem  associated  with  external  documen- 
tation is  that  it  frequently  beoomes  inaccurate  and  outdated 
as  maintenance  proqrammers  make  changes  to  the  prcqraoi  code. 
For  this  reason  maintenance  programmers  tend  to  relay  more 
and  more  en  the  program  listing  as  the  software  system  gets 
older. 
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The  listing  is.  of  necessity,  accurate,  since  it  is  the 
program  in  all  real  senses  of  the  vorl.  For  the  same 
reason.  it  is  complete.  Thus  the  oaly  accurate  and 
current  representation  of  a  orogram,  in  today's  tech- 
nology, is  freguently  the  program  listing.. .If  tha  code 
is  changed,  it  is  much  more  likely  that  the  docuaenta- 
tion  will  be  also.  In  addition,  the  explanations  in  tne 
listing  will  also  likely  to  be  readable  by  the  intended 
taraet  audience,  a  programmer.  They  will  also  be  in 
place  where  he  needs  most  to  find  them.  The  accuracy  and 
completeness  attributes  of  the  listing  will  also  tend  to 
appxy  as  well  to  the  documentation.   [Raf.  43] 

The  main  line  of  thought  being  developed  is  that  recent 
trends  in  programming  technology,  as  presented  in  this 
chapter,  have  shifted  the  emphasis  of  programming  documenta- 
tion from  "external"  documents  to  the  program  listing 
itself.  A  greater  detail  and  quantity  of  information  about 
the  program  is  now  directly  available  to  the  maintenance 
programmer.  This  has  a  significant  impact  on  the  way  one 
should  design  documentation  as  a  whole.  Chapter  IV  will 
discuss  this  point  of  view  as  it  applies  to  a  specific  docu- 
ment, the  Programmer's  Maintenance  lanual,  and  how  it  should 
be  designed. 

1.   Commenting 

It  has  been  stated  that  one  objecti/e  to  imprcve  the 
documentation  of  software  was  to  make  the  program  code 
itself  more  readable.  Two  techniques  already  discussed  were 
structured  programming  and  the  use  of  hi;a  order  languages. 
A  third  technique  is  the  placing  of  comaents  at  appcopiate 
places  within  the  program  code.  One  of  the  main  advantages 
of  a  consistant  commenting  policy  is  its  independence  from 
the  programming  language  used.  There  are  very  few  coapiiers 
that  do  not  allow  comments  to  be  placed  in  the  listing 
[Ref .  40  ]• 

A  second  advantage  is  that  commenting  closes  the  gap 
between  computing  managers  and  computer  ocogrammers.  This 
gaD  develops  because   of  the  programmer's  absolute   aeed  f^r 


48 


attention  to  details.  These  ietails  include  such  items  as 
assembly  language  instruction  choices,  high  order  language 
statement  type  choices,  flag  initialization  procedures,  and 
the  design  of  nested  loops  with  if.. thai  constructs  which 
implement  the  logic  of  the  software  system.  The  manager,  on 
the  other  hand,  must  keep  a  "Big -Picture"  perspective  of  the 
system  and  be  able  to  evaluate  an  elusive  entity  called 
software  guality.  Software  guality  is  often  based  on  items 
such  as  reiiabilty,  readability  and  portablity  [Ref.  38]. 
In  order  to  evaluate  all  these  "-ilities",  the  manager  must 
be  able  to  read  the  program  listing  and  understand  the 
implementation  of  the  software  design  without  necessarily 
being  familiar  with  all  the  in'  s  and  out's  of  a  particular 
program  language. 

Comments  assist  in  putting  more  documentation  into 
the  program  listing  as  well  as  making  the  program  more  read- 
ible.  Comments  explain  details  about  ths  program  that  are 
not  appearent  from  the  code  itself.  TaDle  17  provides  a  list 
of    where      comments    should   appear      in    ths    program.  One    DOD 

activity,  the  Marine  Corp's  Tactical  Systems  Support 
Activity,  has  had  a  great  daal  of  sucoess  in  easing  its 
burden  of  software  maintenance  by  i mpieuenting  a  detailed 
commenting  policy.  Although  SCTSSA's  programs  are  mainly 
written  in  the  Navy's  CUS-2  language,  it  *as  found  that  such 
a  policy  helped  reduce  the  amomt  of  tins  spent  by  program- 
mers en  software  changes  in  addition  to  the  time  savings 
achieve!    by   the    use    of  a    high    order    language.      [Ref.    <*8  ] 
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TABLE    I? 
Recommended    Locations   for   COBiants 


It   the   beginnning    of  eaoa    module.    : 
module    name,    the   currant    date,    the 
its 


nolude   ths 
nodule' s 
function,    its    inputs  and    ou-cputs,    its    limitations 
and    resxrictions,    including   assumptions,    its 
error    processes,    and  the    nama    of   tia    develoDec. 
Sajor    modules    should  also    includa    tha    history 
of    modifications:    for    aach    change,    tha   date, 
the    maintainer's    name,    prupose    of    tha    changa 
and    sccpe. 

At    each   subfunction,    whether    it    ba    a    straight 
sequence  of   code   or   a   logic  branch    or   a    begin- 
erd   block,    an    explanation    of   that    subfunction. 

At  each  interface,  a  claar  dafinition.  of  the 
interface  and  a  referanoa  for  furthar  infor- 
aation  about  the  other  aide  of  xha  interface 
(where    possible)  . 


At  each  < 
related  c 
role   and 


:roup    of    functionally    or   otherwise 
.eclar  ations.    aa    explanation    of   the 
makeup  of    tha    group. 


At    each   declaration,    an    explanation 
of    the    item    and  the   meaning,    if    an/, 
possible   values. 


of    the   role 

of    its 


At  each  dif f icult-to-unia rstand 
an  explanation  of  what  the  code 
complex    solution    was  neoassary. 


urogram    portion 
.oea    and   why    a 


J 
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IV.     TOE    MAINTENANCE    MANCUL 

A-       OBJECTIVES    OF    A    MAINTENANCE    MANUAL 

In  order  to  determine  how  a  progranmsr's  maintenance 
manual  should  be  organized  it  will  be  helpful  to  examine 
some   specific    goals   that    apply   to    any   type    of   manual. 

1 .       General 

The  first  objective  is  to  enumerate  those  general 
organizational  qualities  of  writing  and  style  that  lead  to 
ease  of  use  and  readability  of  technical  publications  and 
documents.  There  are  several  factors  that  insure  the  infor- 
mation contained  in  a  manual  are  is  easy  to  use.  These 
factors  can  be  characterized  into  two  broil  areas.  The  first 
area  concerns  the  concept  that  all  information  presented  by 
the  manual  be  easy  to  find  or  Locate.  The  second  area  is  the 
concept  that,  once  one  finds  :le  information,  the  informa- 
tion is  readily  understood. 

The  factors  that  support  ease  in  finding  information 
are  consistency,  pointers  and  arrangement  [Ref.  50]. 
Consistency  is  the  principle  that  similar  objects  (i.e. 
maintenance  manuals)  containing  the  same  information  (how  to 
understand  and  change  a  computer  program!  be  presented  in 
identical  ways.  In  ether  words,  all  manuals  should  have 
identical  formats.  Readers  of  the  manual  know  what  to 
expect,  how  to  look  for  specific  information  and  where  they 
will  find  it.  For  a  program  maintenance  manual  it  would  be 
helpful  that  details  on  data  structures  be  in  the  same  loca- 
tion in  each  section  cf  the  manual. 
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Pointers  are  essential  signposts  which  identify 
related  groups  of  information.  Pointers  ace  represented  by 
entities  such  as  tables  of  contents,  iaisxes  ani  section 
headings  of  text.  Pointers  anaounce  the  presence  and  loca- 
tion of  information  within  the  body  of  the  manual. 

Arrangement  refers  to  the  manner  of  presentation 
used  throughout  the  manual,  The  arrangement  anticipates  ways 
in  which  readers  might  look  for  specific  information.  The 
subject  of  a  manual  might  typically  be  arranged  by  alphebet- 
ical  or  chronological  order.  Subject  classification  is 
another  method.  For  a  program  maintenance  manual,  the 
arrangement  might  be  related  to  the  hierarchical  design  of 
the  main  functions  and  subfuictions  of  the  program  or  to 
some  external  criteria.  This  criteria  could  be  specified  by 
documentation  standards  incorporated  in  directives. 

The  factors  that  support  ease  of  understanding  are 
simplicity,  concreteness  and  naturalness  [Ref.  50]. 
Simplicity  is  the  concept  that  a  writer  should  use  a  vocabu- 
lary and  writing  style  that  suits  the  intended  readers. 
Admittedly,  cne  assumes  that  any  paricular  person  having  the 
need  to  read  a  maintenance  manual  can  understand  fairly 
complex  compositions.  Still,  the  goal  of  simplicity  is  to 
keep  the  technical  "verbage"  to  a  minimum,  while  presenting 
a  clear  and  logical  flow  of  descriptive  information.  In 
addition,  a  dictionary  or  appendix  sioild  be  included  to 
supply  definitions  of  any  "buzzwords"  for  clarification  and 
consistancy. 

Concreteness  ensures  that  verbal  descriptions  are 
more  specific  than  general.  It  also  impLies  that  examples, 
diagrams  and  pictures  be  provided  for  amplification  and 
clarification.  For  program  maintenance  manuals  the  best  type 
of  diagrams  to  use  has  seen  a  long  history  of  controversy. 
Hierarchy  diagrams,  flow  charts,  Hl?3  charts,  and 
N&SSI-SCNEIDEEMAN  charts,   among  others,   have  seen  the  most 
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usage  "  Ref.  51].  New  developments  sich  as  structured 
program  design  languages  (PDL'si  ,  automated  graphic  packages 
and  abstract  data  typing  for  the  design  process  are  now 
being  used  tc  supplement  verbal  descriptiDns  of  the  software 
[Bef -  49  ]. 

The  concept  of  naturalness  provides  the  reader  with 
the  unfolding  of  information  in  an  ordered  Banner.  It 
ensures  that  readers  can  verify  they  are  on  the  right  track 
and  will  ultimately  find  what  they  are  looking  for 
[Bef.  52]. 

2-   Record  of  Design 

The  second  objective  of  the  programmer's  maintenance 
manual  is  to  provide  programmers  and  management  a  record  of 
the  philosophy  of  design  and  historical  development  of  the 
software.  The  manual  must  include  a  concrete  representation 
of  the  software  design  as  well.  Glass  'Bef-  43]  describes 
four  catagories  of  documents  which  could  be  included  as  part 
of  a  maintenance  manual. 

•  DESIGN  NOT2S 

Design  notes  explain  now  and  why  sections  of  the 
software  evolved  into  their  present  state.  They  should  be 
prepared  in  seme  sort  of  standard  format,  filed  chronologi- 
cally and  cross-indexed  to  the  program  rode.  They  do  not 
have  to  be  detailed  but  should  provide  a  aood  overview  of 
the  concepts  supporting  a  partioular  design ' approach. 

•  £1Q5LEM  R 5PORT.S 

Problem  reports  are  rercrds  of  problems  encountered 
during  the  design  process.  The/  should  describe  the  problem 
and  its  ultimate  solution.  They  are  eventually  placed  in  a 
permanent  historic  file  once  the  final  design  is  fixed.  Ihey 
are  extremely  useful  in  isolating  errors  that  occur  during 
system  testing. 

•  jffPP.QYEHENT    ?2PQRT_S 

Improvement  reports  are  suggestions  and  collections 
of  ideas  held  for  future  changes  to  oe  incorporated  into  the 
software  svstem.  They  can  be  major  improvements  or  cosmetic 
only.  \  reason  for  doing  this  is  to  pass  sound  ideas  of  the 
desianers  to  the  maintenance  programmers.  These  ideas  nay  be 
helpful  when  adding  enhancements  as  a  result  of  changes  in 
user's  requirements. 
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•  IIS.  SI  ON  DESCRIPTION 

Version  descriptions  are  numbsred  changes  that 
Q=scr:i)9  the  modifications  aad  e nhacncements  added  to  a  new 
release  of  the  software.  Each  numbered  change  should  have  a 
complete  list  of  the  changes.  *here  they  ware  made  aad  why, 
a  list  of  the  problem  reports  closed  and  a  description  of 
the  impact  of  the  changes  on  the  users  in  the  user's  tarms. 

The  structure  and  description  of  t:he  software  system 
design  is  best  kept  as  simple  and  straightforward  as 
possible.  Before  the  advent  of  structured  programmir. g  ar.d 
structured  design  tools  (such  as  Program  Design  Languages) 
thare  was  no  standardized  manner  to  represent  the  software 
design.  This  is  still  a  probien  today,  especially  when  one 
desires  to  have  "proofs  of  correctness"  to  determine  that 
the  software  is  free  of  errors  " Ref.  49].  The  best  that  can 
be  done  is  to  use  a  combination  of  items  such  as  hierarch- 
ical block  diagrams  to  list  the  major  modules  and  their 
control/data  flow  relationships,  grouping  of  data  item 
descriptions  into  "clusters"  based  on  usage  of  the  data,  and 
coding  the  design  with  a  well  organized,  modularized  and 
readable  high  order  language. 

3-   Su£port  Maintenance  Pro i rammer i§  Tasks 

The  programmer's  maintenance  mania!  should  be  the 
single  document  that  programmers  need  to  refer  to  for  soft- 
ware maintenance  activities.  The  manual  has  to  be  complete 
in  that  it  must  contain  all  the  information  needed  by 
programmers  to  accomplish  their  two  primary  tasks; 
correcting  errors  (modification*  and  adding  new  capabilities 
(enhancement)  . 

To  support  these  tasks  the  manial  should  be  a  well 
organized,  concise  and  thorougn  description  of  ^he  software. 
It  must  contain  both  an  overall  design  view  and  a  discrete, 
detailed  procedure  by  procedare  view.  It  ias  to  describe  all 
ail  data  items  inputed  to  the  program  (t  ypa/f  ormat/rar.ge)  , 
the  processes  performed   en  the  data,   ani   the  type/format/ 
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range  of  the  output  data.  In  a  real-tins  control  system 
where  the  software  performs  control  functions  based  on  the 
parellel  processing  of  data,  the  logical  control  responses 
to  various  data  inputs  must  be  specified. 

Data  structure  and  organization  ns  to  be  described 
in  detail.  Enumeration  of  lata  names,  descriptions  of 
tables  and  arrays  and  how  they  are  usel,  initialized  or 
otherwise  manipulated  by  the  program  is  of  primary  impor- 
tance. Cross-reference  listings,  which  list  each  data  item 
and  every  module,  function  aid  procedure  where  that,  data 
item  is  used,  are  valuable  aides  for  understanding  the 
program. 

Finally,  two  general  giidelines  mast  be  kept  in  mind 
if  the  manual  is  to  support  the  -asks  Df  the  maintenance 
programmer.  First,  The  manual  must  provide  for  complete 
tracabiiity  from  the  user's  operational  r eguirements  to  the 
actual  program  listing  (lines  of  code)  so  that  if  a  require- 
ment changes  then  the  appreciate  coda  can  be  correctly 
changed,  deleted  or  new  code  added.  Secoad,  the  manual  must 
be.  easily  modified  and  the  change  records!  properly  in  order 
to  reflect  the  changes  to  the  software.  Ef  this  is  not  done 
the  manual  scon  becomes  outdated  and  isaless  as  a  mainte- 
nance tDcl-   [Ref.  U3,  51,  53] 

B.   DEPARTMENT  OF  DEFENSE  REQUIREMENTS 

How  the  objectives  of  a  naintenance  manual  are  best 
fulfilled  is  the  main  topic  of  this  taesis.  DoD  currently 
requires  a  copy  of  the  prsgrara  Listing  and  several 
supporting  documents  for  representing  the  program  lesign. 
Different  DcD  agencies  have  different  raqiirements  for  docu- 
mentation and  various  names  for  individual  documents.  The 
DoD  documents  briefly  described  here  are  from  the  standard 
that   describes  a   Program  Maintenance   Manual   for  ail   DoD 
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activities  (DOD  STANDARD  7935.15)  aid  those  U.S.   Navy  stan- 
dards relating  to  software  maintenance  documentation. 

1-   ££221^21  Maintenance  Manual 

A  description  of  the  DoD  requirenents  for  a  program 
maintenance  manual  is  presented  in  DDD  STANDARD  7935. 1S, 
"Automated  Data  Systems  Documentation  Standards,"  13 
September  1977.  The  standards  main  orientation  is  toward 
documenting  larg«  data  processing  systems,  however,  it  can 
be  used  for  imbedded  tactical  control  systems  as  well.  A 
copy  of  the  format  for  the  Program  Maintenance  Manual  is 
provide!  in  Appendix  A. 

According  to  the  standard,  the  Maintenance  Manual 
(PMM)  is  to  be  divided  into  four  major  sections.  The  first 
section  is  required  to  give  a  general  lescription  of  the 
program;  its  purpose,  history  of  development,  and  define 
other  documents  used  to  support  the  program  (User's  Manual, 
etc.).  The  second  section  contains  a  system  description  to 
include  applications,  functions,  input/output  and  informa- 
tion on  summary  reports.  Details  and  characteristics  of  each 
procedure  and  subroutine  taat  would  be  of  help  to  the 
maintenance  programmer  are  to  d;  stated.  Items  sucn  as  iata 
record  types,  table  character! sites,  =  xit  and  branching 
procedures,  interfaces,  descriptions  of  working  ani  output 
files  must  be  specified.  The  third  section  is  to  describe 
the  operating  environment  to  include  what  support  software 
is  needed.  This  section  is  also  to  contain  a  complete 
description  of  the  data  base  as  well  as  specifying  the 
storage  media  for  the  data  base  (tape,  disk,  or  internal). 
The  fourth  section  is  to  contain  information  on  specific 
maintenance  procedures.  This  will  include  information  on  the 
labeling  of  functions,  subroutines  and  data  records,  along 
with  the  programming  standards  itiiized.  This  section  is  zo 
contain  a  copy  of  the  program  listing  itself. 
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2-  E££<3Eam  Descr  i£tj.on  Document 

The  Program  Description  Document  (PDD)  is  esquired 
by  SECNAVINST  3560.1.  Its  purpose  is  to  provide  a  complete 
technical  description  of  all  procedures,  functions,  data 
structures,  operating  environnsnt,  operating  constraints, 
and  data  base  organization  of  the  software  system.  The  PDD 
is  to  describe  and  completely  define  the  basic  program  logic 
and  program  procedures  for  eaci  system  control  subroutine. 
The  PDD  is  also  required  to  be  directly  related  to  the 
program  design  specifications  which  are  the  formal  func- 
tional requirements  of  the  software  systen.  The  PDD  is,  in 
essence,  the  Navy's  version  of  a  DoD  program  maintenance 
manual.  The  PDD  does  not  contain  a  copy  of  the  program 
listing  or  a  complete  data  base  description. 

3-  Data  Ease  Design  Document 

The  Data  Base  Design  Document  (DBDD)  is  required  by 
the  same  instruction  to  provide  a  complats  detailed  descrip- 
tion of  ail  common  data  items  necessary  to  carry  out  the 
functions  of  the  software  systea  .  lomoiDn  data  is  defined  as 
that  data  required  and  used  dv  two  or  more  subprograms. 
Examples  of  common  data  include  constants,  indexes,  flags, 
variables  and  tables.  The  DBDO  is  to  be  based  on  the  func- 
tional or  performance  specifications.  Ail  terminology  in  the 
DBDD  is  tc  conform  to  the  programming  guidelines  of  the 
program  design  specification  and  the  particular  programming 
language  employed.  The  DBDD  has  to  gi/e  an  organized, 
detailed  description  of  all  lata  objects  to  include  such 
characterisitcs  as  purpose  of  tie  data  object,  field  name, 
size,  nimeric  type  (fixed  point,  floating  point),  range  of 
values,  initialized  condition.  A  cr oss-r s f srence  listing  of 
each  common  data  item  (table,  flag,  etc.)  to  each  program  cr 
subprogram  where  it  is  used  or  set  will  bs  provided. 
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••   p£0£Liam  Package  Document 

The  Program  Package  Document  (PPD)  is  designed  ;o 
consist  of  all  the  program  uaterial  items  such  as  card 
decks,  magnetic  tape,  disk  parks  or  printed  listing  of  the 
software  instructions.  The  PPD  is  to  inolude  an  error  free 
listing  of  a  compilation  of  the  source  program  and  any  data 
which  is  necessary  for  the  program  to  run  properly.  Examples 
of  these  data  items  wculd  be  adaption  data,  data  file  cons- 
tants, set-up  (init ialization)  data  and  program  parameter 
values. 

5-   Problems  with  D3DJ_s  Requirements 

The  DoD  approach,  as  standardized  in  DoD  STANDARD 
7935. 1S,  SECNAVINST  3560.1,  ani  HIL-STD-1 5 79  (Navy)  are  all 
based  or.  the  supposedly  "good  management  practice"  of  having 
the  maintenance  documentation  of  a  software  system  be  a 
complete  set  of  English  text.  Information  concerning  the 
proqram  is  compiled  into  volumes  taat,  in  complex  systems, 
can  reaoh  several  feet  in  width.  All  tiis  text  information, 
as  briefly  outlined  previously,  gives  a  system  overview, 
explains  each  item  and  structure  in  the  system's  data  base, 
shows  control  flow,  data  flow,  nodule  interfaces,  and  major 
functions.  All  this  information,  in  and  of  itself,  is  usable 
by  the  maintenance  programmer.  however,  placing  it  in 
seperate  volumes  is  not  the  best  way  to  present  it.  This 
information  is  much  more  valuable  to  ths  programmers  when 
integrated  into  the  program  listing.  Id  reiterate:  " . . . 
Dcoument at  ion  information  about  a  software  system  belongs, 
in  most  cases,  in  the  listing  of  the  program  itself." 
[Ref.  53]  There  are  three  key  reasons  why  documentation,  to 
the  greatest  extent  possible,  should  be  placed  in  the 
program  listing. 
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The  first  reason  is  that  programiers  tend  to  dislike 
writing  documentation.  They  would  much  rather  bs  writing 
code,  which  is  what  they  do  best  and  feel  the  most  comfor- 
table  with  [ Ref .  54].  If  the  documentation  is  an  iatsgrai 
part  of  the  listing  then  using  readable  data  names,  jotting 
down  a  few  lines  of  comment  to  explain  low  a  procedure  or 
function  works  and  structuring  the  cods  becomes  a  much 
easier  task.  The  programmer  is  saved  frcm  the  tedious 
paper-work  drill  of  having  to  lock  up  a  separata  program 
maintenance  document,  figure  out  how  it's  organized  and 
where  the  needed  information  is  and  thsn  submit  a  change 
outlining  what  program  modif ica tions  or  enhancements  wars 
made.  The  programmer  can  ba  nore  productive  by  combining 
two  steps  into  one  by  keeping  both  -ha  documentation  and 
program  code  up  to  date.  Having  the  cods  and  documentation 
together  can  be  used  by  managers  as  a  motivation  factor  by 
demonstrating  less  work  for  the  programmers  in  the  long  run. 
Other  benefits  can  be  shown' as  in  the  case  of  using  a 
programming  team  to  develop  a  large  software  project.  Hera 
the  team  can  design  the  docume  ntation  as  they  design  the 
structure  of  the  software.  This  can  eliminate  the  need  for  a 
seperate  team  just  to  design  and  write  the  documentation. 
The  documentation  design  can  be  directLy  related  to  and 
supportive  of  the  software  design. 

The  second  reason  for  placing  documentation  in  the 
listing  is  tc  enhance  managements  spaa  of  control.  As 
mentioned  earlier,  there  is  a  large  requirement  for  nanagers 
to  keep  a  big-picture  view  and  be  ao ie  to  supervise,  direct 
and  traok  programmer's  activities  and  progress  while  they 
are  performing  maintenance  tasks.  The  documentation  in  the 
listing  provides  the  means  whereby  a  uaaager  can  evaluate 
changes  to  the  software  and  its  resultant  guality.  Managers 
would  no  longer  be  required  to  evaluate  changes  to  the  code 
and  it's  associated  documentation  and   thea  have  to  check  to 
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make  sure  the  doc  um  e  ct  at  ion  change  corrsctly  reflects  the 
code  change.  In  essence  it  is  desired  to  avoid  a  "iouble- 
entry  bookkeeping"  system  whara  the  documentation  describes 
the  software  as  the  managers  ani  programmers  think  it  works, 
and  the  listing  represents  how  the  software  actually  works. 
[Bef.    53] 

The  final  reason  is  that  a  program  maintenance 
manual  must  remain  accurate  aQl  valid  as  long  as  tiie  soft- 
ware system  is  useful.  Programmers  must  be  able  to  quickly 
logically  use  the  documentation  to  understand  what  a  section 
of  code  is  accomplishing  and  ho*  it  is  doing  so.  Again,  if 
user's  requirements  change,  it  is  essential  that  the  soft- 
ware be  changed  rapidly  and  in  an  error-free  maaner  as 
possible.  If  a  maintenance  programmer  oaaaot  tell  how  the 
code  is  working,  changes  based  on  valil  user  needs,  or  for 
any    other    reason,    will  be   diffioult    at    best. 

C.        A    PROPOSED    "IDEAL"    HAINTENANCE    SANOAL 

To  overcome  the  difficulties  with  upiatir.g  the  documen- 
tation and  ensure  that  the  documentation  is  in  a  form  that 
is  readily  usable  by  programmers  aid  managers  forces  one  to 
consider  a  revised  format  for  a  program  naintenance  manual. 
The  manual  contents  presented  ^iere  are  based  on  ths  advan- 
tages inherent  with  the  quality  and  ietail  that,  the  DoD 
standards  require  and  those  advantages  gained  from  incorpo- 
rating ourrent  software  engineering  prac:ices.  The  "Ideal" 
program  mair.tnenace  manual  will  be  iivided  iatio  four 
sections:  (1)  Overall  Program  Structure,  (2)  The  Program 
Listing,  (3)       A      Data    Dictionary,         aai    (4)         Supplemental 

Appendices . 
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1«   Overall  Program  Structure 

The  overall  program  structure  should  consist:  of 
words  aid  pictures  indicating  bow  the  entire  system  hangs 
together.  A  functional  block  diagram,  which  shows  ail  major 
modules,  procedures  and  functions  is  essential.  This  diagram 
represents  the  system  structure,  the  execution  order  (if 
possible)  and  data  flow.  The  section  should  contain  a  well 
organized  index,  logically  arranged,  which  points  the  way  to 
detail  level  documentation  in  the  listing.  The  index  should 
reflect  the  block  diagram  and  the  design  3f  the  system.  The 
index  should  locate  major  data  structures  and  data  clusters 
within  each  module.  This  section  should  contain  a  written 
text  introduction  to  the  overall  purpose  and  function  of  the 
software,  the  hardware  configuration  used  for  tests  and 
evaluation  prior  to  software  delivery,  and  the  target 
computer  system  (tactical  or  lata  processing)  the  software 
is  to  run  or..  Each  module  of  the  program  will  be  listed,  a 
brief  description  of  the  module  given  ind  the  functional 
relationships/interfaces  with  other  modules  completely 
annotated. 

Finally,  the  section  should  state  the  company 
responsible  for  the  program  iesign  and  development,  the 
names  of  the  chief  programmer  and  members  of  his  team  and 
applicable  references  and  standards  used.  These  standards 
should  include  the  program  performance  specifications,  stan- 
dards for  data  objects,  and  the  language  programming 
standards. 

2-   The  Program  Listing 

The  computer  program  Listing  is  the  single  most 
important  tccl  for  software  maintenance  activities.  The 
objective  of  the  maintenance  maauai  is  to  maximize  th3  main- 
tainability aspect  of   the  listing.   In  tils   regard  clarity 
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and  reaiibility  are  to  be  emphasized  over  efficiency.  It  is 
important  that  the  p.rogram  listing  be  clear,  concise,  struc- 
tured, well  designed,  modularized  and  straightforward. 
[Ref.  48 ]  Each  module  should  contain  a  description  of  what 
the  module  does  and  what  proceiures  or  functions  are 
contained  in  the  module.  Each  module  should  contain  a 
section  for  data  descriptions  or  declarations,  global  and 
local.  Table,  variable  and  flag  declarations  may  be  segre- 
gated and  logically  grouped. 

a.  Physical    Layout 

Good  physical  Layout  is  defined  as  "...that 
property  of  a  program  listing  which  makes  it  capable  of 
being  read  and  understood  by  a  programmer  not  familiar  with 
the  program."  [Ref.  48]  Good  readibility  nay  be  achieved  by 
a  variecy  of  technigues,  some  of  which  are;  seperation  of 
logically  related  groups  of  cole,  seperation  comments  and 
code,  blocking  (by  using  lines  of  asterisks)  lengthy 
comments,  the  appropiate  use  of  blank  lines,  logical  inden- 
tation and  the  lining  up  of  begin-er.d,  if-then/else  pairs. 

All  the  tenants  of  structure!  programming  ,  as 
discussed  in  Chapter  III,  ace  key  ingredients  of  good 
physical  layout.  Figures  3.3  and  3.3  illustrate  this 
physical  structure.  It  may  be  imposed  on  the  code,  as  with 
assembly  language,  or  be  part  of  the  language  syntax,  as 
with  ADA.       [Ref.  38,  39,  42] 

b.  Commenting  and  Naming 

The  use  cf  meaningful  comments  is  of  primary 
importance  to  increase  understanding  of  the  program. 
Comments  should  explain,  amplify  and  supplement  the  listing 
rather  then  echo  the  code.  For  example: 

N  =  N  +  1     --Increment  N 
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— •   A   message   has    just    been    inserted   into    the    message 

—  queue. 

--  Increment  Msg  QUEUE  Pointer  so  that  it  points  to 

—  the  location  where  fhe  next  message  may  be 

--   inserted. 

Msg_2UEUE_Pointer    =  Nsg_Queue_Pointer    «•    1 


Figure   4.1        An   Example    of    Meaningful   Comments. 

does  nothing  to  explain  why  N  is  being  incremented.  A  better 
example   is   illustrated  by    Figure    4.1    . 

If  a  program  module  consists  of  more  than  one 
procedure  or  function  then  there  should  be  commentary  for 
each  procedure  or  function.  The  comments  for  each  procedure 
and  function  should  contain  an  extensive,  detailed  descrip- 
tion of  how  the  procedure  operates  and  its  purpose  in  the 
module.  The  sequence  of  processing  should  be  described  in 
chronological  order  to  include  the  caLiing  sequence  of 
control.  The  hierarchical  structure  of  the  module  can  be 
reflected  in  a  like  manner  as  oomments  follow  the  physical 
indentation.  Table  III  lists  other  criteria  for  commenting 
as    discussed   earlier. 

All  names  for  data  objects,  nodules  and  proce- 
dures must  be  descriptive  in  nature.  They  should  attempt  to 
embody  the  character! sites  of  the  data  item  -hey  represent. 
Names  such  as  ID_3uffer,  SINE_Fu  nction  and  PAT_Roll_3UM  have 
inherent  meanings  and  are  easier  for  the  programmer  to  trace 
through  the  listing.  Names  such  as  A,  X,  S,  or  XYZ  are  mean- 
ingless. Related  data  items  and  procedures  should  have 
related  names  which  demonstrate  their  interconnections. 
[Ref.    43,    44,    48] 
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c.       Data   Declarations   and   Dafinitions 

All  data  items  should  be  grDiped  and  organized 
according  to  their  logical  usage.  Global  data  slenents 
should  be  defined  in  one  location.  LocaL  data  elements  are 
to  described  in  the  procedure  where  they  are  manipulated. 
The  technique  of  information  hiding,  whara  the  structure  and 
characteristics  of  local  data  aid  paranatars  are  unknown  to 
procedures  in  other  modules  [Raf.  2'4  ]f  is  to  be  utilized  to 
the    maximum   extent. 

If  the  programming  language  does  not  support 
strong  data  typing  for  data  declarations,  as  in  the  DoD  high 
order  language  ADA,  then  variable,  tabla,  array  aad  other 
data  declarations  must  contain  meaningful  comments.  These 
comments  are  to  describe  the  purposa,  initial  value,  range 
and  distinct  structure  of  aach.  data  element.  Figure  4.2 
reveals    how   a      data   table    (or    record)       would      be   decLared    in 


type    MONTH    NAME   is     (JAN, F EB,M AR, APR , M AY, JUN, 

JUL,\UG,5SP,DCr,N0V,DEC) ; 


type   DATE    is 
record 


DAY:    INTEGER   raage    1.  .31; 
MONTH:    MONTH    NAME 
YEAR:     INTEGER 
end    record; 


i 


Figure  4.2    Example  of  an  ADA  Data  Table  (Record). 

ADA.  The  table  is  called  ' DAT E'  and  has  three  components 
named  'DAY',  'MONTH',  and  'YEAR'.  DAY  ail  YEAR  are  defined 
to  be  of  type  INTEGER.  MONTH  has  a  separate  type  declara- 
tion called  MONTH  NAME.   INTEGER  is  assuaad  to  be  defined  hv 
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the  support  software  of  the  system  and  hiving  the  mathemat- 
ical characteristics  of  all  integer  numbers.  Variables  and 
constants   associated   with   the   table   DATE   can   then   be 
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Figure   4.3         Example   of    a   C3S-2   Data   Table. 

defined.  An  example  would  be  a  variable  lamed  'D'  belonging 
to  type  DATE.  Before  D  is  used  or  initialized  it  must  be 
further  defined.  This  is  done  by  by  denoting  D  with  a  dot 
followed      by      the      component      name      as      la:  (D.DA5f:  =      4;), 

(D.MONTH:=    JUL;),    and    (D.YEAR:=     177S).       It    is    clear    that    all 
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the  attributes  of  the  table  called  DATE  are  readily  apparent 
tD  the  maintenance  programmer.  The  readioility  of  each  data 
object  clarifies  the  purpose  i nd  structure  of  ths  table. 
[Ref.  44]  Figure  4.3  gives  an  example  Df  a  common  way  to 
declare  a  table  using  the  Navy's  CM5-2  prDgramming  language. 
The  use  of  clear  and  concise  comments  fulfills  similar 
objectives  as  data  typing  in  ADA. 

3-   A  Data  Dictionary 

A  data  dictionary  provides  descriptions  of  indivi- 
dual data  entities  and  can  be  lsed  as  an  index  as  to  where 
the  data  elements  are  declared  in  the  program  listing.  This 
is  extremely  useful  for  large  programs,  i.e.,  greater  than 
10,000  lines  of  code.  The  data  dictionary  can  and  should 
provide  the  formats  for  the  declaration  of  data  within  the 
program  while  being  a  catalog  of  the  data  resources  of  a 
software  system.   [Ref.  55] 

The  data  dictionary  defines  the  logical  organization 
and  physical  organization  of  tie  system's  lata  entities.  The 
logical  organization  specifies  requirements  for  data  access, 
modification,  associativity  and  other  system  orientated 
concerns.  The  physical  organization  defies  file  strictures, 
record  formats,  hardware  depenient  processing  features  and 
database  management  characteristics.  All  lata  structures  and 
the  operations  that  are  to  be  performed  or.  each  structure 
should  be  identified  in  the  dictionary.  The  program  listing 
can  be  referenced  for  details  on  data  elements  and  those 
functions  or  operations  dependent  on  these  elements.  A  data 
dictionary  can  explicitly  represent  the  relationships  among 
data  and  the  constraints  these  elements  place  Dn  data 
structures.  Algorithms  that  may  take  advantage  of  specific 
data  relationships  can  be  more  easily  designed  ar.d  modified 
if  a  dictionary- like  data  specification  exists.   [Ref.  56] 


65 


It  is  appropiate  that  the  data  dictionary  reflect 
the  structure  of  the  program  listing  as  closely  as  possible. 
The  concept  of  "mapping"  the  dictionary  onto  tha  listing 
ensures  the  consistancy  required  by  maintenance  actions.  It 
is  critical  to  the  maintenance  programmer  to  know  which  data 
items  effect  which  particular  modules  aid  vice  versa.  k 
carefully  designed  and  integrated  data  dictionary  is  an 
essential  tool  for  any  modifications  or  enhancements  to  the 
soft  wars . 

**•   iL2£^!lsic.es 

This  section  of  the  maiatenance  manual  is  to  contain 
that  supplementary  information  which  is  of  a  historical 
nature.  Examples  would  be  notes  on  the  development  of  the 
software  design,  problem  reports  and  improvement  reports  as 
described  by  Glass  [Ref.  43].  In  a  seperate  appendix  could 
be  a  complete  description  of  the  intended  operating  environ- 
ment, hardware  configuration  and  operating  system  support 
desired  or  required.  A  continuous  file  of  each  version 
release  and  a  log  of  all  changes  made  to  the  program  (who 
made  them  and  for  what  reason}  should  be  included. 
[Ref.  40,  42,  48] 

A  final  appendix  should  contain  a  set  of  standards 
for  commenting,  algorithmic  structures,  and  the  data 
dictionary.  The  standards  foe  commenting  are  useful  for 
consistancy  and  to  enforce  readioility  of  the  listing. 
Standard  algorithmic  structures  provide  a  framework  for  the 
development  of  module  librari3S.  Such  libraries  can  be 
utilize!  to  add  enhancements  to  the  program  in  a  short 
period  of  time  since  the  modules  involved  are  already  tested 
for  error  free  operation  and  the  functions  or  services 
provided  by  the  module  are  weil  known.  Standards  for  the 
data  dictionary  provide  common  interfaces  between  the 
hardware/software  system  and  ttie  user  organization.   This  is 
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accomplished  by  specifying  the  flow  and  storage  locations  of 
data  entities  within  the  organization  or  rfithin  the  oomputer 
installation  [Ref-  55].  Standards  for  a  lata  dictionary  can 
also  provide  a  library  of  standardized  data  structure  temp- 
lates to  be  used  for  representing  the  logical  and  physical 
characteristics  of  data  entities  within  the  sof-cware  system 
database  [Ref.  56], 
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V.  CONCLUSIONS  &ND  RECOMMENDS TIONS 

The  Department  of  Defense  a  as  an  urgent  requirement  to 
reduce  the  costs  of  software  maintenance  daring  the  coming 
decade.  Recent  advancements  in  the  methods  cf  software 
engineering  such  as  modularization,  structured  design, 
structured  programming  and  data  abstraction  have  contributed 
to  greater  program  comprehension.  This  increased  comprehen- 
sion leads  to  easier  modifications  to  aaet  a  dynamically 
changing  environment. 

It  is  the  opinion  of  this  author  that  the  benefits 
obtained  from  proven  software  engineering  practices  can  be 
realized  in  the  program  maintenance  manaaL.  These  principles 
can  and  should  be  applied  to  the  design  and  standards  for 
such  a  manual.  The  information  available  strickly  from  the 
program  code  itself  forces  us  to  question  the  practice  of 
keeping  the  documentation  seperate  from  tne  code,  and  leads 
to  the  conclusion  that  it  should  not  be  seperate  but 
integrated  into  the  listing. 

With  this  in  mind  the  following  recommendations  are  put 
forth: 

•  The  presen4:  standards  for  software  documentation  be 
revised  to  incorporate  the  most  nseful  aspects  of 
recent  software  engineering  technology. 

•  Studies  should  be  undertacen  with  the  goal  of  standard- 
izing +er minoloqy  for  software  maintenance  documents 
among  all  DoD  activities. 

•  A  framework  has  been  proposed  for  a  orcgram  maintenance 
manual.  This  framework  shoaid  be  implemented  and 
tested  on  various  size  and  types  of  software  systems  to 
discover  what  savings  in  "time  and  money  can  be 
achieved. 
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SECTION  1.   GENERAL  DESCRIPriON 

1.1  Purpose  of  the   Program  M  aint er.aac3  Manual.    This 
paragraph   snail   descriEe   EKe"   purpose   or   the   MM 

(Program  Maintenance  Manual)  in  the  foLlowing  words  or 

apprDpiate  modifications  thereto: 

The  objective  for  writing  this  Program 
Maintenance  Manual  for  (Project  Nans)  (Project 

Number)  is  to  provide  tia  maintenance  programmer 
personnel  with  the  information  necessary  to 

effectively  maintain  the  system. 

1.2  Project  References.    This  paragraph  shall  provide 
a  Brief  summary~oT"tEe  refsrences  applicable   to  the 
history  and   development  of  the  project.    The  general 

nature  of   the  system   (tactical,   inventory   control, 
war-gaming,   management  information.   ate.)   developed 
shall  be  specified.  A  brief  lescriptioi  of  this  system 

shall  include   its  purpose   and  uses.    Also  indicated 

shall  be  the   project  sponsor  and  user  as   well  aa  the 
operating   center(s)    that   will   run   the   completed 

computer   programs.   A   list   of  applicable   docunents 
shall  be   included.   At  least   the  folLowing   shall  be 

specified,    when  applicable,    by   author  or   source, 
reference  number,  title  and  security  classification: 

a.  Users  Manual. 

b.  Computer  Operation  Manual. 

c.  Other  pertinent  documentation  on  the 

project. 

1.3  Terms   and  Abbreviations.     This  paragraph   shall 
provide  a   list  or  include  "in  an  appeidix   anv  termst 
definitions  or   acronyms  unigue   to  this   document  ana 

subject  to  interpretation  by  the  user  of  the  decuaent. 

This  list  will  not  include  item  names  or  data  codes. 

1 
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SECTION    2.    SYSTEM    DESCBIPIIDH 
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tions associated  with  the  use  of  the  data. 
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a.  Identification  -  program  aumbsr  or  tag 
including  a  designation  of  the  version 
number  of  the  program. 

b.  Functions  -  description  of  program  functions 
and  method  used  in  ths  program' to  accomplish 
the  function. 


Input  -  description  of  the  input.  Descriptions 
here  must  include  all  information  pertinent  to 


maim 
(1) 

(2) 

(3) 


ramming,    including: 

s   used    by   the    program   during 


enance    prog 

Data   record 

ooerat  ion 

Input    data 

the    program 

Entry    requirements   concerning    the 

initiation    of   ths    program. 


^y 


wh 


e  a nd  location (s)  used  by 
en  its  operation  begins. 


i 


72 




d.  Processing  -  description  of  the  processing 

• 

per 

formed  by  the  program,  including: 

(D 

Major  operations  -  the  major  operations  of 
program  will  be  described.  The  description 
may  reference  chart  (si  which  ray  be 
included  in  an  appendix.  This  cnart  will 
show  the  general  Logical  flow  of 

operations,  such  is  read  an  input. 

access  a  data  record,  major  decision,  and 
print  an  output  *iich  would  be  represented 
by  segments  or  subprograms  within  the 

program.  Referanca  may  be  made  to  included 

charts  that  prasant  each  major  operation 

in  more  detail. 

(2) 

Major  branching  conditions  provided  in 

(3) 

the  program. 

Restrictions  that  have  been  designed  into 

the  system  with  raspect  to  the  operation 

of  this  program,  or  any  limitations  on 

the  use  of  the  program. 

Exit  reguirements  concerning  termination 

(<*) 

of  the  operation  of  tha  program. 

(5) 

Communications  or  linkage  to  the  next 
logical  program  (operational,  control). 

(6) 

Output  data  type  and  location  (s) 
produced  by  the  program  for  use  by 

related  processing  segments  of  the 

system. 

Storage  -  Specify  the  amount  and  type  of 

(7) 

storage  required  to  use  tha  program  and 

the  broad  parameters  of  the  storage 

locations  needed. 

2  .   OUT! 

put  -  description  of  the  outDUts  produced 

by 

the  program.  While  this  description  may 

ref 

erence  output  described  in  tie  Users  Manual, 

any 

intermediate  output,  working  files,  etc. 

should  be  described  for  the  benafit  of  the 

mai 

ntenance  programmer. 

f.  Int 

erfaces  -  description  of  the  interfaces  to 

from  this  program. 

g.  Tab 

les  and  Items  -  provide  details  and 

characteristics  of  the  tables  aid  items  within 

eac 

h  program.  Items  not  part  of  a  table  must 
listed  seDerately.  Items  contained  within 

be 

a  - 

able  may  be  referenced  from  the  table 

descriptions.  If  the  data  descnotion  of  the 

pro 

pre 

gram  provides  sufficient  information,  the 
gram  listing  may  be  referencad  to  provide 

_ 

some  or  the  necessary  information.  kt~  least 

3 
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the  following  will  be  included  for  each  table: 

1)  Table  tag,  labia  or  symboLic  name. 

2)  Full  name  and  purpose  of  the  table. 
,3)  Other  prograas  that  use  this  table. 

(4)  Logical  divisions  within  the  table 
(internal  table  blocks  or  Darts  -  not 
entries)  . 

(5)  Basic  table  structure  (fixed  or  variable 
length,  fixed  or  variable  entry 
structure) . 

(6)  Table  layout  f  a  graphic  scesentatiaa 
should  be  used},  incxuded'  in  supporting 
description  should  be  table  controlling 
information,  details  of  the  structure  of 
each  type  of  entry,  unique  or  significant 
characteristics  or  the  use  of  the  table, 
and  information  about  the  names  and 
locations  of  items  within  the  table. 

(7)  Items  -  the  teen  "item"  refers  to  a 
specific  category  of  detailed  information 
that  is  coded  for  direct  and  immediate 
manipulation  by  a  program.  Used  in  this 
sense,  the  definition  of  an  item  is 
machine-  and  program-oriented  rather 
than  operationally  oriented.  Of  primary 
importance  is  an  explanation  of  the  use 
of  each  item.  At    least  the  following 
will  be  included  for  each  item: 

a)  Item  tag  or  label  aid  full  name. 

b)  Purpose  of  the  itero. 

c)  Item  coding,  depending  upon  the 
item  type,  such'as  integer, 
symbolic,  status,  etc. 

Unique  Run  Features  -  description  cf  any 
unique  features  of  trie  running  of  this 
program  that  are  not  included  ii  the 
Computer  Operation  Manual. 
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SECTION  3.  ENVIRONMENT 

3.1   Equipment   En vironment.     This   oaragraph  shall 
discuss  the   equipment-configuration   and  its   general 

characteristics  as  they  apply  to  the  system. 

3.2  Support  Software.    This   paragraph  shall  list  the 
various  support  software  used  by   tha  system  and  iden- 

tify t 
system 

he  version  or   release  number   laier  which   the 

was  developed. 

3.3  Data   Base.    Information  in  this   paragraph  shall 
Incluae   a~  complete   description  of   tha   nature   and 

conten 

t  of  each  data  base  usad  by  tha  system. 

3.3.1 

cTescf  i 

General  Characteristics.    Pro/ide   a   ganaral 
ptlon  of   cSe*"cEaracE"af  isti  cs  of  the   data  base, 

inclad 

:ng: 

a. 

Identification  -  name  and  mnemonic  reference 

of  the  component  (a.g.  data  bassl .  List  tha 

programs  utilizing  ttia  component  and  explain 
the  use  of  the  componant  in  tha  system. 

b. 

Permanency  -  note  whather  the  component 

contains  static  data  that  a  program  can 

reference,  but  may  nst  change,  3C  dynamic 

data  that  can  be  changed  or  updated  during 

system  operation.  Indicate  whather  the  change 

is  periodic  or  random  as  a  function  of  input 

data. 

— -  • 

Storage  -  specify  tha  storage  madia  for  tha 
data  Dase  (e.g.  tape,  disk,  intarnal  storage) 

and  the  amount  of  storage  required. 

i. 

Restrictions  -  explain  why  li nit  a tions  on 

the  use  of  this  conpoient  by  tha  program  in 

the  system. 

3.3.2 
paragr 
of  the 

Organization  and   Detailed  Descrigtion.     This 
aph"  will  serv9"Io  IsfTne  Ehe  Infernal  structure 

data  base.    A  layout   will  be   shown  and   its 

compos 
explai 

ition,    such  as   records  and   cables,   will   be 

red.   If  available,   computer  generated  or  other 

list in 

gs  af   this  detailed   information  may   be  refer- 

enced 

or  included  herein.  Tha  following  items  indicate 

the  t  y 

pe  of  information  desired: 

a. 

Lavcut  -  show  the  structure  of  the  data  base 

including  record  and  items. 

b. 

Sections  -  note  whether  tie  physical  record 

is  a  logical  record  or  one  of  several  that 

constitute  a  ioaical  record.  Identify  the 

record  parts,  such  as  healer  or  control 

segments  and  the  body  of  the  reoord. 

5 
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c.    Fields   -   identify   sash    field   in    the   record 
structure  and,    if    necessary,    explain    its   purpose. 
Include    for    each    field    tie    following    items: 

(1)  Tags/labels   -    indicate   the   tag    or    label 
assigned    to    reference   each   field. 

(2)  Size  -    indicate  the    length    ani    number   of 
bits/characters   that    maice   up    each    data 
field. 

(3)  Range   -   indicate   the    range   of    acceptable 
values   for  the  field    entry. 


d.    Expansion   -   note   provisions,    if 
adding  additional  data    fields   to 


the 


for 

recori. 
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SECTION  4.  PROGRAM  MAINTENANCE  PROCEDURES 

Section  4  of  the  manual  shall  provide  information  on 
the  specific  procedures  necessary  for  the  programmer 
to  maintain  the  programs  that  make  up  the  system. 

4.1  Conventions.  This  paragraph  will  explain  all 
rules,  sclnemesj  and  conventions  that  have  been  used 
within  the  sy_stem.  Information  of  tiis  nature  could 
include  the  rollowing  items. 

a.  Design  of  mnemonic  identifiers  and  their 
application  to  the  tagging  or  labeling  of 
programs,  subroutines,  records,  data  fields, 
storage  areas,  etc. 

b.  Procedures  and  standards  for  charts,  listings, 
serialization  of  cards,  abbreviations  used  m 
statements  and  remarks,  and  symbols  appearing 
in  charts  and  listings. 

c.  The  appropiate  standards,  fully  identified, 
may  be  referenced  in  lieu  of  a  detailed  ouiine 
of  conventions. 

d.  Standard  data  elements  and  related  features. 

4.2  Verification  Procedures .  This  paragraph  will 
inclu  c!e~Hiose  reguif ements~and  procedures  necessary  to 
check  the  performance  of  a  program  section  following 
its  sodif ication.  Included  nay  also  be  orocedures  for 
the  periodic  verification  of  the  prograiu 

^•1  £££££  Conditions.  A  description  of  error  condi- 
tions.  '  not   previously   documented,     may   also   be 

included.  This  description  shall  include  an  explana- 
tion of  the  source  of  the  error  and  recommended 
methods  to  correct  it. 

4.4  Special  Maintenance  Procedures.  This  paragraph 
shall  contain  any  special  "procedures  required  which 
have  not  been  delineated  elsewhere  in  this  section. 
Specific  information  that  may  be  appropiate  for 
presentation  shall  include: 

a.  Requirements,  porcedures,  and  verification 
which  may  be  necessary  to  maintain  the  system 
input-output  components,  such  as  the  data 
base. 

b.  Requirements,  procedures,  and  verification 
methods  necessary  to  perform  a  Library 
Maintenance  System  run. 

*-5  Sp.eci.ai  Maintenance  Proarams.  This  paragraph 
shall  contain"an  in ventory""of  "any  soecial  orograms 
(such  as  file  restoration,  purging  historical  files) 
used  to  maintain  the  system.  These  programs  should  be 
described  in  the  same  manner  as  those  described  in 
paragraphs  2.3  and  2.4  of  the  MM. 
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a.   Input-Output  Reauiren  ents. 

Ip.clutlea  in  tsis  paragraph  "fhall  3e  tha  require- 
ments concerning  the  equipment  and  materials  needed  to 
support  the  necessary  maintenance  tasks.  Materials 
may,  for  example,  include  card  decks  for  loading  a 
maintenance  program  and  the  inputs  which  represent  the 
changes  to  be  made.  When  a  support  system  is  being 
used,  this  paragraph  should  reference  the  < 
manual. 


appropiate 


b«  Procedures 
The  procedures,  presented  in  a  step-by-step  manner, 
shall  detail  the  method  of  preparing  tie  inputs,  such 
as  structuring  and  sequencing  of  inputs.  The  opera- 
tions or  steps  to  be  followed  in  setting  up,  running, 
and  terminating  the  maintenance  task  nn  the  equipment 
shall  be  given. 

4.6  Listings.  This  paragraph  will  contain  or  provide 
a  reference"  to  the  location  of  the  program  listing. 
Comments  appropiate  to  particular  instructions  shall 
be  Dade  if  necessary  to  understand  and  follow  the 
listing. 
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